Contributing to Documentation

This page outlines what you need in order to contribute to the documentation, along with the various markdown attributes and so forth you can use.

The documentation is hosted using GitHub Pages and is written in Markdown format, using MkDocs to publish the content. We use the MkDocs Material theme to give us the framework for the look and feel of the website, along with a number of other useful plugins and extensions to enhance the content.

Important! Once up and running with the information on this page, please ensure you are familiar with general markdown syntax.

Refer to the Markdown Guide.

How to Contribute

For contributions from the general public, we recommend forking the GitHub repository and submitting pull requests for the DCC-EX Documenter team to review and merge.

If you wish to contribute more fully and become a part of the DCC-EX Documenter team, reach out to us via Discord. To gain access to the GitHub repository, one of the DCC-EX team administrators will need to add you to the "Web" team in GitHub.

MkDocs Links

Here are some handy links with more info:

• MkDocs website - The official MkDocs documentation.
• MkDocs Material theme - The MkDocs Material theme documentation.
• MkDocs Awesome Nav plugin - MkDocs Awesome Nav plugin is what we use for dynamic page structure.
• MkDocs RSS plugin - The MkDocs RSS Plugin publishes our DCC-EX News feed.
• MkDocs Open in New Tab plugin - The Open in New Tab plugin ensures all links to external websites open in a new tab to ensure the users' browsing experience in our documentation is consistent.

What You Need to Install

This is the list of software you need to successfully contribute to the documentation, including being able to preview it locally:

• Visual Studio Code (VSCode)
• Python - Version 3.13 is recommended, minimum required is 3.10

There are two VSCode plugins that are highly recommended also:

• Markdown Preview Mermaid Support by Matt Bierner - enables previewing Mermaid diagrams in VSCode
• markdownlint by David Anson - helps keep consistent, good formatting in Markdown files (like flake8 for Python)

Getting Started

Once you have installed VSCode and Python, you need to clone the GitHub repository, set up a virtual environment, and install the MkDocs requirements.

We recommend using the built-in Git functionality of VSCode to clone the repository, or you can use GitHub Desktop or command line Git, whichever you prefer. There is plenty of information generally available on that so we won't cover it here, and instead will focus on the specifics required to ready to contribute to MkDocs content.

Follow the appropriate section below to setup MkDocs in Python for your operating system:

Setup on macOS

cd mkdocs-test
python 3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Setup on Linux

cd mkdocs-test
python3 -m venv venv
. ./venv/bin/activate
pip install -r requirements.txt

Setup on Windows

cd mkdocs-test
virtualenv venv
venv\scripts\activate
pip install -r requirements.txt

Previewing and building MkDocs

Previewing locally is very simple:

mkdocs serve

Navigate to the local preview in a browser.

When finished with the local preview, stop the local server with either Ctrl+C (Windows/Linux) or Cmd+C (macOS).

Building locally is equally as simple:

mkdocs build

MkDocs also has a feature to deploy to GitHub pages without using a workflow:

mkdocs gh-deploy