Skip to content

docs: refresh README (AI-assisted) #942

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
igorpecovnik wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: refresh README (AI-assisted) #942

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 99 additions & 18 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,57 +1,138 @@
<h2 align="center">
<a href=#><img src="https://raw.githubusercontent.com/armbian/.github/master/profile/logosmall.png" alt="Armbian logo"></a>
<a href="#"><img src="https://raw.githubusercontent.com/armbian/.github/master/profile/logosmall.png" alt="Armbian logo"></a>
<br><br>
</h2>

### Purpose of This Repository
# Armbian Documentation

Armbian Documentation serves as the central knowledge base for the entire Armbian ecosystem. It covers everything from the **Armbian OS** and **armbian-config** utility to **software modules** and the **Armbian build framework**. Whether you're installing Armbian for the first time, configuring advanced features, or building custom images from source, the documentation provides step-by-step guides, best practices, and technical references to support both beginners and experienced developers.
[![Create offline documentation to release](https://github.com/armbian/documentation/actions/workflows/release.yaml/badge.svg)](https://github.com/armbian/documentation/actions/workflows/release.yaml)
[![Create docs preview on PR](https://github.com/armbian/documentation/actions/workflows/pdf-at-pr.yaml/badge.svg)](https://github.com/armbian/documentation/actions/workflows/pdf-at-pr.yaml)

## Contribute
Source repository for the [Armbian Documentation](https://docs.armbian.com) — the central knowledge base for the Armbian ecosystem, covering the Armbian OS, `armbian-config`, software modules, and the Armbian build framework.

You can contribute to Armbian Documentation directly on [GitHub](docs/) by editing or submitting pull requests.
However, to **enjoy a fully rendered local preview** with proper styling and live reload, we recommend setting up the documentation site locally using `mkdocs`.
## Overview

Documentation is written in [Markdown](https://www.markdownguide.org/basic-syntax/) and stored in the [`docs/`](docs/) subfolder. Images live in `docs/images/`. This repository is intended for storage and quick browsing on GitHub — the official rendered output is published at:

* Website: [https://docs.armbian.com](https://docs.armbian.com)
* PDF: [Latest release](https://github.com/armbian/documentation/releases/latest)

The site is built with [MkDocs](https://github.com/mkdocs/mkdocs/) using the [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme (see [`requirements.txt`](requirements.txt) and [`mkdocs.yml`](mkdocs.yml)).

## Repository Layout

```
docs/ Markdown content, images, and CSS
images/ Screenshots and diagrams
css/ Custom stylesheets
overrides/ Theme overrides (main.html)
tools/ Helper scripts (mkArmbianDocs.py)
.github/ Workflows, labels, PR/issue templates
mkdocs.yml MkDocs site configuration
requirements.txt Python dependencies
```
Comment on lines +24 to +33

@coderabbitai coderabbitai Bot Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Specify languages for fenced code blocks.

Add text (or another appropriate language) to both fences to satisfy Markdown linting and improve rendered documentation.

Proposed fix 
-```
+```text
 ...
-```
+```

Also applies to: 43-45

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 24-24: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 24 - 33, Specify a language on both fenced code
blocks in the README repository-tree examples, including the additional fence
around lines 43–45. Use text or another appropriate language identifier while
preserving the existing contents.

Source: Linters/SAST tools


## Contributing

You can contribute directly on GitHub by editing files under [`docs/`](docs/) and opening a pull request. For a fully rendered local preview with styling and live reload, set up MkDocs locally as shown below.

Please review the [document template](.github/DOCUMENT_TEMPLATE.md) before writing new content.

### File naming convention

```
[Parent-Topic]_[Child-Topic]-example.md
```

Parent and child topics are separated by an underscore (`_`). Hyphens (`-`) are automatically converted to spaces when rendered. Please avoid creating new parent topics unless absolutely necessary.
Comment on lines +41 to +47

@coderabbitai coderabbitai Bot Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
rg -n 'ParentCategory|Parent-Topic|split|findFiles|parseFiles' README.md tools/mkArmbianDocs.py

Repository: armbian/documentation

Length of output: 657

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== README excerpt ==\n'
sed -n '38,50p' README.md

printf '\n== tools/mkArmbianDocs.py excerpt ==\n'
nl -ba tools/mkArmbianDocs.py | sed -n '1,120p'

Repository: armbian/documentation

Length of output: 659

🏁 Script executed:

#!/bin/bash
set -euo pipefail

nl -ba tools/mkArmbianDocs.py | sed -n '1,120p'

Repository: armbian/documentation

Length of output: 199

🏁 Script executed:

#!/bin/bash
set -euo pipefail

printf '\n== tools/mkArmbianDocs.py (1-240) ==\n'
awk '{printf "%4d %s\n", NR, $0}' tools/mkArmbianDocs.py | sed -n '1,240p'

printf '\n== search for filename handling ==\n'
grep -nE 'split|replace|Parent|Child|Category|Subtopic|example' tools/mkArmbianDocs.py

Repository: armbian/documentation

Length of output: 7411

Align the generator help text with the parser contract. tools/mkArmbianDocs.py already accepts underscore-separated names like [Parent-Topic]_[Child-Topic]-example.md; the argparse description still says [ParentCategory]-Subtopic.md, which is misleading for contributors.

🧰 Tools
🪛 markdownlint-cli2 (0.23.0)

[warning] 43-43: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 41 - 47, Update the argparse help text in
tools/mkArmbianDocs.py to describe the parser’s underscore-separated filename
convention, using the [Parent-Topic]_[Child-Topic]-example.md format instead of
[ParentCategory]-Subtopic.md. Keep the README convention and parser behavior
unchanged.


Current parent topics:

* User Guide
* Hardware notes
* Developer Guide
* Contributor Process
* Release management
* Community

## Building Locally

### Prerequisites

Ensure Python and the required development packages are installed:

```bash
sudo apt-get update
sudo apt-get install python3 python3-pip python3-venv python3-dev
```

If using Debian, you may need to install the following packages for `mkdocs-material`:
On Debian you may additionally need the following packages for `mkdocs-material`:

```bash
sudo apt-get install libcairo2 pango1.0-tools
```

### Cloning the Repository

Next, clone the Armbian documentation repository:
### Clone the repository

```bash
git clone https://github.com/armbian/documentation
cd documentation
```

### Setting Up the Environment
### Set up the environment

Set up a Python virtual environment to isolate the project dependencies:
Use a Python virtual environment to isolate dependencies:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install --use-pep517 -r requirements.txt
```

### Running the Local Server

To preview the documentation locally:
### Build and serve

```bash
mkdocs build --clean
mkdocs serve -a 0.0.0.0:8000
```

Then open your browser and go to http://localhost:8000
The site will automatically reload when you make changes to .md files.
Then open [http://localhost:8000](http://localhost:8000). The site auto-reloads when `.md` files change.
Comment on lines 94 to +99

@coderabbitai coderabbitai Bot Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win

Bind the local preview to localhost by default.

0.0.0.0:8000 exposes unpublished documentation to every reachable network interface. Use 127.0.0.1:8000 for a local-preview instruction, and document the broader bind only for intentional remote access.

Proposed fix 
-mkdocs serve -a 0.0.0.0:8000
+mkdocs serve -a 127.0.0.1:8000
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```bash
mkdocs build --clean
mkdocs serve -a 0.0.0.0:8000
```
Then open your browser and go to http://localhost:8000
The site will automatically reload when you make changes to .md files.
Then open [http://localhost:8000](http://localhost:8000). The site auto-reloads when `.md` files change.
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@README.md` around lines 94 - 99, Update the README’s mkdocs serve command to
bind the local preview to 127.0.0.1:8000 instead of 0.0.0.0:8000, and mention
the broader 0.0.0.0 binding only as an intentional option for remote access.


> 💡 Tip: Use the local preview to verify formatting and layout before committing your changes.

## Tooling

The `tools/` folder contains helper scripts used to maintain the documentation.

### `tools/mkArmbianDocs.py`

Regenerates `mkdocs.yml` from the current contents of the `docs/` folder.

* Only needed when the **structure** of `docs/` changes (new sections, renamed topics, etc.).
* Supports command-line options for input and output directories — see `mkArmbianDocs.py -h`.

Run from the repository root:

```bash
python3 tools/mkArmbianDocs.py && mkdocs build
```

This regenerates `mkdocs.yml` and publishes the built HTML to `site/`.

## Automation

This repository uses several GitHub Actions workflows:

| Workflow | Purpose |
|----------|---------|
| `release.yaml` | Builds the site with MkDocs and deploys it to `docs.armbian.com` on pushes to `main`. |
| `pdf-at-pr.yaml` | Builds a docs preview for each pull request and publishes it to the `www` branch, then comments a preview link on the PR. |
| `pull-from-armbian-config.yml` | Pulls content generated by [`armbian/configng`](https://github.com/armbian/configng) into `docs/User-Guide_Armbian-Config/` and `docs/User-Guide_Armbian-Software/`, and opens an auto-update PR. |
| `pull-mirrors-from-db.yml` | Regenerates the mirrors table in `docs/Mirrors.md` from the Armbian NetBox database and opens an auto-update PR. |
| `pr-announce.yml` / `merge-announce.yml` | Announce new PRs and merges on Discord. |
| `pr-auto-labeler.yml` / `labels-from-yml.yml` | Automatic PR labeling (category, size) and label sync from `.github/labels.yml`. |
| `clean-workflow-logs.yml` | Weekly cleanup of old workflow run logs. |

## License

💡 Tip: Use the local preview to verify formatting and layout before committing your changes.
This project is licensed under the [GNU General Public License v3.0](LICENSE).
Loading