Our documentation is written as Markdown files and served via GitHub Pages by MkDocs.
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
<del></del>tags with~~. -
Tables adds support for tables to standard Markdown.
When creating new documents, they should be added to the
mkdocs.yml file
in the appropriate place under nav: to get them to appear in the sidebar navigation.
For example:
nav:
- Introduction: index.md
When running cfgov-refresh using Docker-compose, this documentation is running by default at http://localhost:8888.
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 :8888Once running, they are accessible at http://localhost:8888.
Every time a PR is merged to master, GitHub Actions will build and deploy the documentation to https://cfpb.github.io/cfgov-refresh/. See How we use GitHub Actions for more info.
If you would like to deploy to a fork of cfgov-refresh owned by another user
you can provide the -r argument:
mkdocs gh-deploy -r USERWhere 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.