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¶
pyenv activate consumerfinance.gov 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 consumerfinance.gov 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/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.
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.