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 <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

Running the docs locally

With Docker

When running cfgov-refresh using Docker-compose, this documentation is running by default at http://localhost:8888.

Manually

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

Every time a PR is merged to master, Travis will build and deploy the documentation to https://cfpb.github.io/cfgov-refresh. See How we use Travis CI 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 USER

Where 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.