- 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!
- 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".
- On the repository's main page, on the Code tab, click Add file > Create new file.
- 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.
- Add a message if you like, and click Commit new file.
- Wait just a few seconds, then go to your new page, https://username.github.io. For an example, go to annegentle.github.io.
- 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:
- 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 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.
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.
When you want to allow the docs team members to maintain docs within a code repo, while giving the docs team autonomy over their own reviews and merges, you can use a protected branch and a CODEOWNERS file.
Sysdig’s journey from unstructured to structured, and finally, to semi-structured authoring and how Sysdig hackathon enabled designing their homegrown docs-like-code solution.
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.
Review the results of a mid-2020 survey about learning and teaching team mates and yourself how to work with docs like code, Git, and GitHub for technical documentation.
Learn about one team’s journey to keep a long-term relationship with their docs-like-code system, TechDocs, which is open source and available to all.
Welcome to part 4 of our article series, where we take a look under the hood, discuss the technologies we used, how we built our auto-generated API Reference, and how we use GitHub for our docs as code workflow and more.
Learn some pro tips to build Python Sphinx developer docs to both GitHub Pages and your local system.
Welcome to part 3 of our article series where we explore how we collaborate with our community.
Why Redis is joining the revolution of open source docs.
Welcome to part 2 of our article series where we discuss how content production started, and how we created the layouts and navigation for the site.