We use a select few MkDocs plugins to achieve the following:
- minify HTML (:octicons-octoface-24:)
- display the date of the last Git modification of every page (:octicons-octoface-24:)
- automatically generate docs based on code and docstrings (:octicons-octoface-24:)
- export the site as a PDF (:octicons-octoface-24:)
We also depend on a few Python-Markdown extensions to achieve the following:
- support for emojis, collapsible elements, code highlighting, and other advanced features courtesy of the PyMdown extension suite (:octicons-octoface-24:)
- ability to inline SVG icons from Material, FontAwesome, and Octicons (:octicons-octoface-24:)
- allow arbitrary scripts to modify MkDocs input files (:octicons-octoface-24:)
- automatically generate reference docs for Click-based command line interfaces (:octicons-octoface-24:)
All references are automatically available to all pages.
These allow for the expansion of text on hover, useful for acronyms and definitions.
For example, if you add the following to the list of abbreviations:
*[CERN]: European Organization for Nuclear Research
then anywhere you type CERN the organization's full name will appear on hover.
All links to external resources should be added to the list of external links rather than defined on a per-page basis, for many reasons:
- it keeps the Markdown content compact and thus easy to read and modify
- the ability to re-use a link, even if you forsee no immediate use elsewhere
- easy automation of stale link detection
- when links to external resources change, the last date of Git modification displayed on pages will not
We use some scripts to dynamically modify pages before being processed by other extensions and MkDocs itself, to achieve the following:
- add references to the bottom of every page
- render the status of various aspects of integrations
- enumerate all the dependencies that are shipped with the Datadog Agent
To build and view the documentation in your browser, run the serve command (the first invocation may take a few extra moments):
ddev docs serve
By default, live reloading is enabled so any modification will be reflected in near-real time.
Note: In order to export the site as a PDF, you can use the
Never make documentation non-deterministic as it will trigger deploys for every single commit.
For example, say you want to display the valid values of a CLI option and the enumeration is represented as a
set. Formatting the sequence directly will produce inconsistent results because sets do not guarantee order like dictionaries do, so you must sort it first.