DEV Community

Cover image for How to create a Profile README for your Organisation
Michelle Mannering for GitHub

Posted on

How to create a Profile README for your Organisation

You've heard, seen, and probably have your own GitHub Profile README. Did you know you can now do the same for an organisation?

If you are an org maintainer or owner, you can create an organisation profile README that will appear on your organisation's home page.

Step 1. Create .github folder

In order to create the organisation README, you'll need a special location for this README file. Just like a profile README is hosted under github.com/YOUR_USERNAME/YOUR_USERNAME, an organisation README lives in a special place too.

    1. Go to your organisation
    2. Click "New" to create a new repository

New

    3. Type `.github` and you'll see that you've discovered a _secret_

Secret

    4. Make sure the repo is public and click "Create repository"

Create

Now you have the repo setup for your organisation README.

Step 2. Create README.md

Since organisation profile READMEs are a new feature, GitHub has added some fancy buttons to help make this step super easy.

Now that you have your new .github repo, go to this new repo you created in Step 1.

On the right side of the screen, you should see a nice green box to help you set up your profile. Click the button that says "Add profile README".

Add

This will add a folder under your repo called profile, and will create a README.md file in this folder with some suggestions to help you get started.

CleanShot 2021-09-16 at 10.47.19@2x

You can also do this manually by clicking "Add file" --> "Create new file" and typing: profile/readme.md.

README Profile folder

Now that you have your README.md file created, it's time to add content!

Step 3. Add content

Like other READMEs, Profile READMEs are written in GitHub Flavoured Markdown. You can add text, images, gifs, and emojis. Add whatever you like to showcase your organisation.

README

Check out some of our Markdown updates:

As well as tips on creating your README file, complete with snippets of code for you to use:

Step 4. Commit

Once you're happy with your Markdown file, commit your code. Don't forget, you can use the "Preview" button while writing your README file to see how your Markdown will render.

Profile

Step 5. Show it off!

Your organisation profile README is now be available on your organisation's Overview page.

Profile README

You can also check out other organisation profile READMEs. Do you have an organisation README setup? Drop the link below so we can all see it!

If you want to find out more about org profile READMEs, check out the GitHub Docs.

Check out our video on creating your org profile README:

Discussion (2)

Collapse
danbamikiya profile image
Dan Bamikiya

Hi, great article! It would be nice if we could follow an organization so we don't have to star/watch all their repos!

Collapse
adriens profile image
SALES

DONE 👍