Documentation is written in markdown and stored in the docs/
subfolder. Images go in docs/images
.
This repo is meant for storing and quick glances. Official output is https://docs.armbian.com.
Armbian Documentation is available in the following formats:
This site is built with mkdocs and depends on mkdocs-material.
Armbian Documentation naming of document files follows this rules:
[Parent-Topic-Example]_[Child-Topic]-example.md
Parent-Topic-Name
and Child-Topic-Name
are separated by an underscore _
. Hyphens -
are automatically converted to space.
Please try to avoid creating new parent topics unless absolutely necessary.
Current Parent Topics:
- User Guide
- Hardware notes
- Developer Guide
- Contributor Process
- Release management
- Community
See the document template before you writing any content.
Ensure you have Python and the necessary development packages installed:
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv python3.11-dev
Next, clone the Armbian documentation repository:
git clone https://github.com/armbian/documentation
cd documentation
Set up a Python virtual environment to isolate the project dependencies:
python3 -m venv .venv
source .venv/bin/activate
pip install --use-pep517 -r requirements.txt
To build and serve the documentation locally, allowing you to make edits and observe the results in real time, use:
mkdocs build --clean && mkdocs serve
You will be able to make edits to existing files and observe the results in real time.
After adding a new file, either hand-edit mkdocs.yml
, or re-run tools/mkArmbianDocs.py
unless making changes to the structure of the docs/
folder. (See below)
Generate mkdocs.yml
based on the contents of docs/
folder
- Command-line options for input and output directories
- Requires install requirement
- You don't need to run it every time unless making changes to the structure of the
docs/
folder - See
mkArmbianDocs.py -h
for help
From the parent folder of the repo, run:
python3 tools/mkArmbianDocs.py && mkdocs build
This will generate the mkdocs.yml
and publish built HTML to the site/
folder.