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

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

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

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".

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.

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

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.

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.

Step 5. Show it off!

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

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: