Getting Started
- Overview
- Setting Up Your Documentation Site
- Building Your Site Locally (Optional)
- Building Your Documentation Site Further
Overview
This page walks you through the process of creating a GitHub Pages documentation site for your repository.
Setting Up Your Documentation Site
To begin building out your documentation website, you will need to set up the initial structure in your own repository.
Much of the work has been done for you in setting up the GitHub Pages site via a template that can be downloaded as a zip file at this link. Download this template and place the docs folder in your repository.
This template lays most of the groundwork necessary for the GitHub pages repository and in fact, can be committed and built by GitHub right out of the box. But first, you must enable GitHub to build GitHub Pages websites for you from within the repository.
Note, if you would like to change the theme of the GitHub Pages site - to include a blog, for example - you can follow the instructions found under the Advanced Topics.
Enabling GitHub Pages For Your Repository
Before GitHub will build your Pages site for you, you will need to enable it from the repository settings from on the GitHub website. To do this, follow these steps:
- Go to your repository’s “Settings” tab on the GitHub website. We have included a picture of where this is located in the repository’s navigation bar on GitHub below:
- Scroll down to the “GitHub Pages” settings in the “Settings” tab. This will look like the following picture:
-
Click the “Source” dropdown menu and click the “master branch /docs folder” option.
This will publish your GitHub Pages website to
https://<YOU_GITHUB_USERNAME>.github.io/<REPO_NAME>/.
Building Your Site Locally (Optional)
This is an optional step, but one that will save you lots of headache and frustration down the road.
GitHub takes some time to build your website and publish it. Due to this, the process of committing, pushing, allowing for GitHub to build the website and publish it, then finally checking your website for errors can be incredibly drawn out and inefficient. To skip all of these steps, you can immediately check that your website is built correctly by building it on your local machine.
To build your site locally, see the “Building Locally” page.
Building Your Documentation Site Further
Now that the groundwork has been laid for your GitHub Pages website, it’s time to build out your website. There are a few conventions and best practices that we use that you can read about at this page.