Getting started ¶
This is a template repository to enable rapid creation of documentation sites built using
mkdocs and served via
GitHub Pages under Cal-ITP’s
Create new site from template ¶
Follow these steps to create a new repository that uses this repository as a template. Content from the new repository will be
published online at
Adapted from GitHub’s documentation.
Head to the generate repository page for this template:
Configure the new repository’s details, including the Owner (
cal-itp), Name, and Description
Ensure the new repository’s visiblity is set to Public
Ensure the checkbox to Include all branches is checked
Click Create repository from template to finish and create the new repository
Finalize the new site ¶
Once the above steps are complete and the new repository is ready, it’s a good idea to clean up the remnants of the template.
- Review the
LICENSEfile and ensure it is appropriate for your new project. If not, update it with a more appropriate license before continuing.
- Find+Replace instances of
mkdocs-templatewith the name of your new repository.
- Edit the
docs/.pagesfile to update your site’s navigation menu, or delete the file to generate a navigation menu for the site automatically. Read more about the
How does this work? ¶
mkdocs turns markdown content inside the
docs/ directory into HTML+CSS+JS needed for a website.
mkdocs.yml file in the root of the repository
configures website settings and available plugins for this build process.
docs/requirements.txt file lists the
python dependencies necessary to build the documentation using
GitHub Actions ¶
A GitHub Action called
mhausenblas/mkdocs-deploy-gh-pages enables automated
building of new documentation content using
mkdocs, whenever the content changes. Our workflow is defined in the
The action uses the
docs/requirements.txt file to install the necessary dependencies for building the docs site.
mkdocs, the action redeploys the documentation site by force-pushing to the
GitHub Pages ¶
GitHub Pages serves the website from the
gh-pages branch of this repository.
GitHub Pages for Organizations functions such that any repository created in the Cal-ITP Organization, with
GitHub Pages enabled, will have an automatic domain at