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 Python and the necessary development packages are installed. For Debian-based systems:
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv python3.11-dev
Set up a Python virtual environment to isolate project dependencies. This example uses a directory within the current user's home directory, but you can adjust the path as needed:
python3 -m venv ~/armbian-docs-env
source ~/armbian-docs-env/bin/activate
Alternatively, for a project-specific environment, replace ~/armbian-docs-env
with ./env
or another directory within your project's folder.
Clone the Armbian documentation repository and navigate into it:
git clone https://github.com/armbian/documentation
cd documentation
Install the required Python packages from the requirements.txt
file:
pip install -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
This command builds the documentation and starts a local server. You can view the documentation by visiting http://127.0.0.1:8000
in your web browser.
- For editing existing files: After making changes, the
mkdocs serve
command automatically rebuilds the documentation. Simply refresh your browser to see the updates. - For adding new files: Ensure the new files are referenced in the
mkdocs.yml
configuration file under thenav
section. The server automatically incorporates changes, so just refresh your browser to view them.
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.