You've already forked documentation
mirror of
https://github.com/armbian/documentation.git
synced 2026-01-06 10:13:36 -08:00
108 lines
3.2 KiB
Markdown
108 lines
3.2 KiB
Markdown
# Armbian Documentation
|
|
|
|
[](https://github.com/armbian/documentation/actions/workflows/release.yaml)
|
|
|
|
<p align="center">
|
|
<a target="_blank" href="https://docs.armbian.com">
|
|
<img alt="logo" src="./docs/images/logo.png">
|
|
</a>
|
|
</p>
|
|
|
|
## Overview
|
|
|
|
Documentation is written in [markdown](https://www.markdownguide.org/basic-syntax/) 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](https://docs.armbian.com).
|
|
|
|
Armbian Documentation is available in the following formats:
|
|
|
|
* [Official document website](https://docs.armbian.com),
|
|
* [PDF document](https://github.com/armbian/documentation/releases/latest)
|
|
|
|
## Contributing
|
|
|
|
This site is built with [mkdocs](https://github.com/mkdocs/mkdocs/) and depends on [mkdocs-material](https://github.com/squidfunk/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](.github/DOCUMENT_TEMPLATE.md) before you writing any content.
|
|
|
|
## Working on the content
|
|
|
|
### Prerequisites
|
|
|
|
Ensure you have Python and the necessary development packages installed:
|
|
|
|
```bash
|
|
sudo apt-get update
|
|
sudo apt-get install python3 python3-pip python3-venv python3.12-dev
|
|
```
|
|
|
|
If using Debian, you may need to install the following packages for `mkdocs-material`:
|
|
|
|
```bash
|
|
sudo apt-get install libcairo2 pango1.0-tools
|
|
```
|
|
|
|
### Cloning the Repository
|
|
|
|
Next, clone the Armbian documentation repository:
|
|
|
|
```bash
|
|
git clone https://github.com/armbian/documentation
|
|
cd documentation
|
|
```
|
|
|
|
### Setting Up the Environment
|
|
|
|
Set up a Python virtual environment to isolate the project dependencies:
|
|
|
|
```bash
|
|
python3 -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install --use-pep517 -r requirements.txt
|
|
```
|
|
|
|
### Building and Serving the Documentation
|
|
|
|
To build and serve the documentation locally, allowing you to make edits and observe the results in real time, use:
|
|
|
|
```bash
|
|
mkdocs build --clean
|
|
mkdocs serve -a 0.0.0.0:8000
|
|
```
|
|
|
|
You will be able to make edits to existing files and observe the results in real time.
|
|
|
|
## Generate tools
|
|
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)
|
|
|
|
### mkArmbianDocs.py
|
|
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.
|