1. Create a GitHub account at github.com. Refer to GitHub Pro Account or GitHub Free Account for Technical Writing if you're wondering which pricing plan makes sense for you. Free is likely fine!
  2. In your browser, create a repository with the same name as your GitHub username, followed by "github.io". For example, my repository name is "annegentle.github.io".
  3. On the repository's main page, on the Code tab, click Add file > Create new file.

    GitHub Add file and Create file

  4. In the Name your file... field, enter "index.md" and under Edit new file, add a line or two of text that you want to publish as your new web landing page.

    GitHub Edit new file

  5. Add a message if you like, and click Commit new file.

    GitHub Commit new file

  6. Wait just a few seconds, then go to your new page, https://username.github.io. For an example, go to annegentle.github.io.
  7. If you don't see a page, check the settings for GitHub Pages by going to the Settings tab for the repository, and then click Pages in the left-hand side. The Settings should look similar to these:

    GitHub repository Settings then Pages sidebar

  8. Go to pages.github.com for even more scenarios.

    That exercise gives you a taste of using GitHub as a content management system and publishing to a single web page automatically by pushing to a branch. Learn more by exploring the rest of this site.

Learn more

Learn the tools


Learning GitHub or any system backed by `git` takes some time and practice. Try some lessons with multiple static site generators and deployment systems as well as how to test docs as code.

Docs Like Code Book

Buy the book


We've transformed the way teams work together on docs, and we want to talk about the best practices for writing docs using development tools and techniques. Now in its second edition.

Read the articles

Read more articles on this site about using GitHub for documentation. Let's find out the best practices and create a balance point between artisanal craft and automation efficiency.

Setting up Techdocs on Backstage

Techdocs is Spotify’s homegrown docs like code solution. it allows the user to store documentation to near code thus allowing it to be easily discovered.