How to create a Profile README for your Organisation
Tags: github, opensource, tutorial
Published: 2021-09-17 00:59:03

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.

<ol>1. Go to your organisation </ol>
<ol>2. Click "New" to create a new repository </ol>
![New](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/57q1r8pbjad1tuqx40oa.JPG)
 
<ol>3. Type `.github` and you'll see that you've discovered a _secret_ </ol>

![Secret](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n3mps0ecihax9ug2w9gq.JPG)
 
<ol>4. Make sure the repo is public and click "Create repository" </ol>
![Create](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4pwot51zbe98lmenqr96.JPG)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/rod6d6zpdy8ekphyjkyx.JPG)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ylv30odw6r5d0l0qex1u.png)

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

![README Profile folder](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ee50vw2efo9pgmmqeefx.JPG)

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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8wm5c91n4zzdkazvqx0m.JPG)

Check out some of our Markdown updates:

{% link https://dev.to/github/updates-to-github-markdown-making-it-easier-for-you-to-build-amazing-things-49fj %}

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

{% link https://dev.to/github/how-to-create-a-github-profile-readme-jha %}

## 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](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i4ke4ltefxe9ad70his7.JPG) 

## Step 5. Show it off!

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

![Profile README](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4cp27x74q0btqtz425xl.JPG)

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](https://docs.github.com/en/organizations/collaborating-with-groups-in-organizations/customizing-your-organizations-profile).

Check out our video on creating your org profile README:

{% youtube oQnJ6XYp_YM %}