Contributing to the Docs¶
Our documentation is written as Markdown files and served via GitHub Pages by MkDocs.
Writing the docs¶
As our documentation is written in Markdown, the base Markdown specification is a useful reference. MkDocs also includes some documentation to get you started writing in Markdown.
In addition to standard Markdown, our documentation supports the following extensions:
Admonitions adds specially called-out text anywhere within the document as notes, warnings, and other types.
BetterEm improves the handling of bold and italics.
MagicLink provides automatic linking for URLs in the Markdown text.
SuperFences makes a number of improvements to standard Markdown code fences.
Tilde adds support for creating
Tables adds support for tables to standard Markdown.
When creating new documents, they should be added to the
in the appropriate place under
nav: to get them to appear in the sidebar navigation.
nav: - Introduction: index.md
Running the docs locally¶
When using the stand-alone installation of cfgov-refresh, you can run these docs with:
workon cfgov-refresh pip install -r requirements/docs.txt mkdocs serve -a :8888
Once running, they are accessible at http://localhost:8888.
Deploying the docs to GitHub Pages¶
If you would like to deploy to a fork of cfgov-refresh owned by another user
you can provide the
mkdocs gh-deploy -r USER
USER is the GitHub user.
The docs will then be available at https://USER.github.io/cfgov-refresh/ after a short period of time.
See the the MkDocs documentation for more information.