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

See Running documentation site locally.

Deploying the docs to GitHub Pages

Every time a PR is merged to main, GitHub Actions will build and deploy the documentation to https://cfpb.github.io/consumerfinance.gov/. See How we use GitHub Actions for more info.

If you would like to deploy to a fork of consumerfinance.gov 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/consumerfinance.gov/ after a short period of time.

See the the MkDocs documentation for more information.

Public vs. private documentation

Some internal documentation is not suitable for inclusion in the public docs.

Warning

Internal documentation can be linked from publicly-viewable documentation only if internal domain names and URLs are not shared publicly.

To support such linking, the consumerfinance.gov Wagtail admin has a custom "Internal documentation" setting that allows for dynamic linking to an internal URL without exposing that URL in public source code or documentation.

Defining this setting adds a "Internal documentation" item to the Wagtail admin "Help" menu. This menu item then links to the configured setting URL. Defining this setting also creates an /admin/internal-docs/ alias URL that redirects to the configured setting URL. This alias URL can be shared or referenced publicly without exposing the internal one.