docs: refresh README (AI-assisted)#942
Conversation
github-actions
Bot
added
size/medium
WalkthroughREADME.md was rewritten as a structured index for the Armbian Documentation repository. It now covers the repository layout, contribution and file-naming guidance, local MkDocs setup and serving, documentation tooling, GitHub Actions automation, and the GPL v3 license. The header also adds branding, workflow badges, and links to published documentation and PDF outputs. Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with 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.
Inline comments:
In `@README.md`:
- Around line 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.
- Around line 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.
- Around line 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.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| ``` | ||
| 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 | ||
| ``` |
There was a problem hiding this comment.
📐 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
| ### 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. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
rg -n 'ParentCategory|Parent-Topic|split|findFiles|parseFiles' README.md tools/mkArmbianDocs.pyRepository: 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.pyRepository: 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.
| ```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. |
There was a problem hiding this comment.
🔒 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.
| ```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.
1 participant
Automated README refresh generated by the Maintenance: Update README (AI)
workflow in
armbian.github.io.The content is generated by Claude from this repository's own files (file tree,
manifests, workflows, existing README). Please review for accuracy before
merging — edit or close if anything is wrong. Re-running the workflow refreshes
this branch.
Documentation website preview will be available shortly:
Open WWW preview