How to Contribute

Getting Started

Material for MkDocs is a framework on top of [MkDocs], a static site generator for project documentation. Generally there two ways to accomplish a live preview, either in a reduced fashion directly your local editor or an extensive and full preview based on MkDocs itself. If you are having issues with User Account Control/Permissions, the editor based live preview is the simplest and fastest way to go! If you wish to skop any local installations, complete the Cloning our Knowledge Base Repository and head to Making Changes and adding Pages

Cloning our Knowledge Base Repository

Installing Python (only for Mkdocs Live Preview)

The easiest way is to install (and update) Python via the Microsoft Store. Alternatively, you can download/install Python for Windows directly.

Installing Material for MkDocs (only for Mkdocs Live Preview)

Once installed, head over to your local copy/cloned Knowledge Base repository/folder (via Windows Explorer) and open a Terminal (Windows PowerShell) session by right clicking the root folder of your repository (i.e. /site-kb.ross-tech.de/) and selecting "Open Terminal". With your terminal session running, Material for MKdocs is published as a Python package and can be installed with pip in a virtual environment.

PS> python -m venv venv\
PS> venv\Scripts\activate.bat
(venv) PS D:\site-kb.ross-tech.de> pip install mkdocs-material
(venv) PS D:\site-kb.ross-tech.de> pip install "mkdocs-material[imaging]"
(venv) PS D:\site-kb.ross-tech.de> pip install mkdocs-glightbox
(venv) PS D:\site-kb.ross-tech.de> pip install mkdocs-include
(venv) PS D:\site-kb.ross-tech.de> pip install mkdocs-macros-plugin
(venv) PS D:\site-kb.ross-tech.de> pip install mkdocs-redirects
(venv) PS D:\site-kb.ross-tech.de> pip install mkdocs-sitemap-exclusion

Utilizing the MkDocs Live Preview

To start the live preview, open your Knowledge Base repository/folder (via Windows Explorer) and start a Terminal (Windows PowerShell) session by right clicking the root folder of your repository (i.e. /site-kb.ross-tech.de/) and selecting "Open Terminal".

PS> venv\Scripts\activate.bat
(venv) PS D:\site-kb.ross-tech.de> mkdocs serve --livereload

Now click the link in your Terminal window or point your browser to localhost:8000.

If you are having troubles or need to cancel/stop the live preview, press Ctrl+C.

Making Changes and adding Pages

I have been using Visual Studio Code in combination with the Extensions Markdown All in One and Markdown Preview Enhanced, but as Notepad++ likely offers similar features and/or extensions/plugins.

The editor based live preview will give a "as-you-type" like preview, while the MkDocs live preview "only" refreshes files after actually saving them and it goes through the entire site build process. So for quick edits/additions, you can certainly rely on the editor based preview alone.

Commit your Changes and Additions

Identical to your known workflow for Label Files etc. you can now work with this system.

Create a new branch like /%yourname%/%date%-%subject%/
Create a new file like /docs/dtcs/XYYYY.md or use an existing one as reference/copy.
Make and review your changes and additions.
Commit your finalized work product.
Create a Merge Request.