Reorganizing and rewriting the documentation #665
Conversation
Add a preface section. Start restructuring to achieve the following end structure: - Preface - Introduction - Configuration - Advanced Topics - Troubleshoot - Appendixes ...
Update commands and outputs. Reorder some content. Also fix a few typos in the process.
…ubleshotting section
no content changes
can't decide if we should move the config stuff not handled by armbian-config into this section
Sort out later
The discussion result was to move this topic.
WalkthroughThe updates encompass multiple documentation files and a reorganization of the navigation structure. A comment has been added to the configuration guide suggesting a future move of content on sound and screen resolution. The Getting Started guide has been renamed and restructured to clarify prerequisites, download contents, verification procedures, deployment steps, and boot processes. The dedicated Recovery guide has been removed, with its content largely integrated into an expanded Troubleshooting guide that now includes detailed sections on power management, SD card usage, U-Boot shell access, network issues, and recovery procedures. The main index has been revised with updated section titles and an enhanced structure for navigating the documentation. Additionally, changes in the mkdocs configuration reorganize the navigation hierarchy by introducing new entries and consolidating previous topics into categories such as Advanced Usage, Troubleshooting and Recovery, and an Appendix. No modifications were made to any exported or public entity declarations. 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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
docs/User-Guide_Getting-Started.md
Outdated
|
|
||
|
|
||
| ### Minimal, Server, and Desktop? | ||
| ### Minimal, Server, or Desktop? |
There was a problem hiding this comment.
Minimal, Server or Desktop?
without the second comma?
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (19)
docs/User-Guide_Configuration.md (2)
3-4: TODO Comment: Consider Reassigning Advanced Topics
The comment suggests moving elements such as sound output or screen resolution information to an "Advanced tasks" section. Please review whether relocating these topics would improve the document’s overall clarity and, if so, update the section organization accordingly.
1-2: Overall Formatting and Consistency Check
The document is well structured with clear command examples, but please double-check punctuation and any potential typographical issues (e.g., ensuring consistency in hyphenation where advisable) based on internal style guides.docs/User-Guide_Troubleshooting.md (8)
30-37: Content Clarity: Power Supply Section
The "Powering notes" and subsequent "Power supply" instructions are detailed and informative. Please consider incorporating the suggested hyphenation (e.g. "feedback-based stabilization") from static analysis to enhance readability.🧰 Tools
🪛 LanguageTool
[uncategorized] ~34-~34: This expression is usually spelled with a hyphen.
Context: ... cheap phone chargers don't have proper feedback based stabilization, so output voltage may ch...(BASED_HYPHEN)
🪛 markdownlint-cli2 (0.17.2)
30-30: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
44-49: Suggestion: Connector Section Clarity
The instructions on connector ratings and alternate powering options are useful. A minor language tweak—such as clarifying "rated for the maximum current"—could improve the technical precision of this section.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
44-44: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
56-61: Review: SD Card Brand Recommendations
The recommended brands and the rationale provided are helpful for users trying to avoid counterfeit products. Consider adding hyperlinks or references to detailed test results in future updates.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
56-56: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
67-73: Content Check: SD Card Testing
This section effectively warns about the risks of counterfeit or degraded SD cards. It may be beneficial to elaborate slightly on how tools like F3 or H2testw compare, aiding novice users in making informed decisions.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
67-67: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
74-81: Review: Writing Images to the SD Card
The step-by-step instructions for verifying image writes are well presented. Consider adding or updating links to official resources for tools like balenaEtcher so users know where to find the latest information.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
74-74: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
133-142: Evaluation: Recovery Section Structure
The recovery section is comprehensive, detailing everything from preliminary diagnostics to flashing boot loaders. For improved readability, consider breaking it into smaller sub-sections if possible and incorporate the static analysis suggestions (e.g., proper hyphenation) where applicable.🧰 Tools
🪛 LanguageTool
[typographical] ~142-~142: It seems that a comma is missing.
Context: ...# U-Boot Shell Access If you broke the system you can try to get in this way. You ha...(IF_COMMA)
🪛 markdownlint-cli2 (0.17.2)
139-139: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
189-264: Re-Flash and Recovery Procedure
This section provides thorough procedures for replacing/bootand recovering system functionality. A review for minor language corrections (including punctuation and hyphen usage) is recommended to align with the overall documentation style.🧰 Tools
🪛 LanguageTool
[uncategorized] ~191-~191: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...boot When something goes terribly wrong and you are not able to boot the system (an...(COMMA_COMPOUND_SENTENCE)
[style] ~191-~191: As a shorter alternative for ‘able to’, consider using “can not”.
Context: ...n something goes terribly wrong and you are not able to boot the system (and cannot gain access...(BE_ABLE_TO)
[uncategorized] ~191-~191: This expression is usually spelled with a hyphen.
Context: ...the way to proceed. You will need some Debian based Linux machine where you can mount the f...(BASED_HYPHEN)
[typographical] ~191-~191: It appears that a comma is missing.
Context: ...an mount the failed SD card. With this procedure you will reinstall the kernel and hardw...(DURING_THAT_TIME_COMMA)
[formatting] ~191-~191: Insert a comma after ‘cases’: “In most cases,”?
Context: ...tall the kernel and hardware settings. In most cases this should be enough to unbrick the bo...(IN_MOST_CASES_COMMA)
[uncategorized] ~193-~193: This expression is usually spelled with a hyphen.
Context: ...nd partition(s), respectively (if not a flash based device, it may even be/dev/sdXY, etc...(BASED_HYPHEN)
[style] ~193-~193: In American English, abbreviations like “etc.” require a period.
Context: ...sed device, it may even be/dev/sdXY, etc). ``` console / # fsck /dev/mmcblkXpY ...(ETC_PERIOD)
[style] ~244-~244: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ....8.16 dtb ``` If you upgrade from some very old build, you might need to update your bo...(EN_WEAK_ADJECTIVE)
🪛 markdownlint-cli2 (0.17.2)
198-198: Trailing spaces
Expected: 0 or 2; Actual: 1(MD009, no-trailing-spaces)
198-198: Hard tabs
Column: 1(MD010, no-hard-tabs)
264-265: Overall Document Review
This troubleshooting guide covers a wide range of potential issues and resolutions. A final pass to address minor language or formatting suggestions (as flagged by static analysis) will help improve overall clarity and consistency.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
265-265: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
mkdocs.yml (2)
114-118: Navigation Update: Advanced Usage
The "Advanced Usage" section now cleanly groups advanced topics (Advanced Features, Networking, Firstboot config). Consider revisiting the commented “Device tree overlays” item—if it remains relevant, its placement might need to be reconsidered.🧰 Tools
🪛 YAMLlint (1.35.1)
[warning] 114-114: too many spaces before colon
(colons)
[warning] 115-115: wrong indentation: expected 14 but found 12
(indentation)
[warning] 116-116: too many spaces before colon
(colons)
10-171: Overall Navigation Reorganization
The changes in the navigation structure effectively improve the clarity and accessibility of the documentation. It would be beneficial to address the YAML indentation and spacing warnings (if not already fixed) for long-term maintainability.🧰 Tools
🪛 YAMLlint (1.35.1)
[warning] 15-15: wrong indentation: expected 8 but found 6
(indentation)
[warning] 21-21: wrong indentation: expected 14 but found 12
(indentation)
[warning] 27-27: wrong indentation: expected 14 but found 12
(indentation)
[warning] 40-40: wrong indentation: expected 4 but found 2
(indentation)
[warning] 43-43: wrong indentation: expected 4 but found 2
(indentation)
[warning] 44-44: wrong indentation: expected 6 but found 4
(indentation)
[warning] 47-47: wrong indentation: expected 6 but found 4
(indentation)
[warning] 55-55: wrong indentation: expected 4 but found 2
(indentation)
[warning] 63-63: wrong indentation: expected 4 but found 2
(indentation)
[warning] 67-67: wrong indentation: expected 8 but found 6
(indentation)
[warning] 69-69: wrong indentation: expected 8 but found 6
(indentation)
[warning] 78-78: wrong indentation: expected 8 but found 6
(indentation)
[warning] 79-79: wrong indentation: expected 10 but found 6
(indentation)
[warning] 89-89: wrong indentation: expected 8 but found 6
(indentation)
[warning] 91-91: wrong indentation: expected 8 but found 6
(indentation)
[warning] 94-94: wrong indentation: expected 8 but found 6
(indentation)
[warning] 98-98: wrong indentation: expected 8 but found 6
(indentation)
[warning] 102-102: wrong indentation: expected 8 but found 6
(indentation)
[warning] 104-104: wrong indentation: expected 10 but found 8
(indentation)
[warning] 105-105: wrong indentation: expected 12 but found 10
(indentation)
[warning] 110-110: wrong indentation: expected 4 but found 2
(indentation)
[warning] 112-112: too many spaces before colon
(colons)
[warning] 113-113: too many spaces before colon
(colons)
[warning] 114-114: too many spaces before colon
(colons)
[warning] 115-115: wrong indentation: expected 14 but found 12
(indentation)
[warning] 116-116: too many spaces before colon
(colons)
[warning] 119-119: too many spaces before colon
(colons)
[warning] 121-121: too many spaces before colon
(colons)
[warning] 122-122: too many spaces before colon
(colons)
[warning] 123-123: wrong indentation: expected 14 but found 12
(indentation)
[warning] 123-123: too many spaces before colon
(colons)
[warning] 124-124: too many spaces before colon
(colons)
[warning] 125-125: too many spaces before colon
(colons)
[error] 137-137: trailing spaces
(trailing-spaces)
[warning] 148-148: too many spaces before colon
(colons)
[warning] 149-149: too many spaces before colon
(colons)
[warning] 150-150: too many spaces before colon
(colons)
[warning] 151-151: too many spaces before colon
(colons)
[warning] 152-152: too many spaces before colon
(colons)
[warning] 153-153: too many spaces before colon
(colons)
[warning] 154-154: too many spaces before colon
(colons)
[warning] 155-155: too many spaces before colon
(colons)
[warning] 156-156: too many spaces before colon
(colons)
[warning] 157-157: too many spaces before colon
(colons)
[warning] 159-159: too many spaces before colon
(colons)
[warning] 160-160: too many spaces before colon
(colons)
[warning] 161-161: too many spaces before colon
(colons)
[warning] 162-162: too many spaces before colon
(colons)
[warning] 164-164: too many spaces before colon
(colons)
[warning] 165-165: too many spaces before colon
(colons)
[warning] 167-167: too many spaces before colon
(colons)
[warning] 168-168: too many spaces before colon
(colons)
[warning] 169-169: too many spaces before colon
(colons)
[warning] 170-170: too many blank lines
(1 > 0) (empty-lines)
docs/User-Guide_Getting-Started.md (4)
10-17: Video Tutorial Section
The inclusion of a video tutorial within an admonition ("!!! tips") block is a helpful addition. Please follow up on the TODO items to add relevant links or updated information as needed.
19-24: Download Image Instructions
The "Download the image" header and accompanying instructions are now well-organized. The TODO about adding UI-related information is noted—ensure that this is updated in a subsequent commit if possible.
26-53: Image Type Descriptions
The distinctions among image types (Minimal, Server, Desktop; Vendor, Current, Edge, Legacy; Rolling releases) are clearly articulated. Consider adding links or references to more detailed benchmarks or test outcomes to support users in their choice.🧰 Tools
🪛 LanguageTool
[misspelling] ~37-~37: This word is normally spelled with a hyphen.
Context: ...phical user environment - Desktop - full featured desktop image For some boards we provi...(EN_COMPOUNDS_FULL_FEATURED)
[typographical] ~39-~39: It appears that a comma is missing.
Context: ...- full featured desktop image For some boards we provide only minimal images due to t...(DURING_THAT_TIME_COMMA)
[typographical] ~44-~44: It appears that a comma is missing.
Context: ...ndor, Current, Edge, or Legacy In some cases we provide images with different firmwa...(DURING_THAT_TIME_COMMA)
[grammar] ~47-~47: A determiner may be missing.
Context: ...releases.html) and is in most cases the best choice. Use the following images only...(THE_SUPERLATIVE)
[style] ~49-~49: Consider using a more polite wording.
Context: ...e are the only ones provided, or if you want to participate in testing: - edge ...(IF_YOU_WANT)
243-247: Automated Config Note
The tip regarding automated configuration is a valuable addition. Please consider clarifying in a follow-up update that this step only preps the SD card, as indicated by the TODO.🧰 Tools
🪛 LanguageTool
[misspelling] ~244-~244: This word is normally spelled as one.
Context: ...mated config" These settings can be pre-loaded, see [Autoconfig](/User-Guide_Autoconfi...(EN_COMPOUNDS_PRE_LOADED)
docs/index.md (3)
17-21: Advanced and Troubleshooting Sections
The distinction between basic content and advanced topics is well established. Please revisit the TODO note in line 23 regarding appendixes (Changelog, Releases, Model, FAQ) to ensure future completeness.
88-110: Comparison Table
The comparison table is informative and well laid out. Please address the TODO regarding appendixes and double-check that the information presented is fully up to date.🧰 Tools
🪛 LanguageTool
[misspelling] ~100-~100: This word is normally spelled with a hyphen.
Context: ...dern | | Build framework | advanced and user friendly | none | none | | Hardware maintainers ...(EN_COMPOUNDS_USER_FRIENDLY)
133-135: Contribution Guidelines Placeholder
The "How can you contribute?" section is marked as "tbw." It would enhance the documentation to provide at least a basic outline or link to contribution guidelines in the near future.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (6)
docs/User-Guide_Configuration.md(1 hunks)docs/User-Guide_Getting-Started.md(6 hunks)docs/User-Guide_Recovery.md(0 hunks)docs/User-Guide_Troubleshooting.md(3 hunks)docs/index.md(3 hunks)mkdocs.yml(2 hunks)
💤 Files with no reviewable changes (1)
- docs/User-Guide_Recovery.md
🧰 Additional context used
🪛 LanguageTool
docs/User-Guide_Getting-Started.md
[style] ~3-~3: Consider using a different verb to strengthen your wording.
Context: ...Started Guide Before you start, please make sure you have: - a proper power supply acco...
(MAKE_SURE_ENSURE)
[misspelling] ~37-~37: This word is normally spelled with a hyphen.
Context: ...phical user environment - Desktop - full featured desktop image For some boards we provi...
(EN_COMPOUNDS_FULL_FEATURED)
[typographical] ~39-~39: It appears that a comma is missing.
Context: ...- full featured desktop image For some boards we provide only minimal images due to t...
(DURING_THAT_TIME_COMMA)
[typographical] ~44-~44: It appears that a comma is missing.
Context: ...ndor, Current, Edge, or Legacy In some cases we provide images with different firmwa...
(DURING_THAT_TIME_COMMA)
[grammar] ~47-~47: A determiner may be missing.
Context: ...releases.html) and is in most cases the best choice. Use the following images only...
(THE_SUPERLATIVE)
[style] ~49-~49: Consider using a more polite wording.
Context: ...e are the only ones provided, or if you want to participate in testing: - edge ...
(IF_YOU_WANT)
[uncategorized] ~61-~61: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...suitable for Linux enthusiasts who want cutting edge packages and have the skills to fix the...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[misspelling] ~187-~187: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...he serial console. For SSH, you need to login as root and use the password **1234...
(LOG_IN)
[misspelling] ~244-~244: This word is normally spelled as one.
Context: ...mated config" These settings can be pre-loaded, see [Autoconfig](/User-Guide_Autoconfi...
(EN_COMPOUNDS_PRE_LOADED)
[style] ~251-~251: The phrase ‘in many cases’ is used quite frequently. Consider using a less frequent alternative to set your writing apart.
Context: ...lling it onto your device's hard-drive. In many cases, you probably want to apply some basic ...
(IN_MANY_STYLE_CASES)
[uncategorized] ~265-~265: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...ge, nothing has been installed onto the boards internal drive yet. Using the installer...
(AI_HYDRA_LEO_APOSTROPHE_S_XS)
[misspelling] ~265-~265: This word is normally spelled as one.
Context: ...w decide, where you want to install the boot loader and the rest of the system. The install...
(EN_COMPOUNDS_BOOT_LOADER)
[grammar] ~280-~280: The word ‘install’ is not a noun.
Context: ... user a sensible default --> Start the install script and follow the lead: armbia...
(A_INSTALL)
[uncategorized] ~286-~286: The preposition ‘on’ seems more likely in this position.
Context: ...2/nandsata.png) After you have decided for an option, you can choose between the f...
(AI_HYDRA_LEO_REPLACE_FOR_ON)
[style] ~323-~323: Using many exclamation marks might seem excessive (in this case: 27 exclamation marks for a text that’s 10256 characters long)
Context: ...n-config](/User-Guide_Armbian-Config). !!! danger Userspaces distribution upgr...
(EN_EXCESSIVE_EXCLAMATION)
[uncategorized] ~325-~325: A comma may be missing after the conjunctive/linking adverb ‘Therefore’.
Context: ...rades are neither tested nor supported. Therefore Armbian cannot provide any support if s...
(SENT_START_CONJUNCTIVE_LINKING_ADVERB_COMMA)
[misspelling] ~328-~328: This word is normally spelled as one.
Context: ... something goes wrong. ### Update the boot loader First, you need to update all packages...
(EN_COMPOUNDS_BOOT_LOADER)
docs/User-Guide_Troubleshooting.md
[uncategorized] ~34-~34: This expression is usually spelled with a hyphen.
Context: ... cheap phone chargers don't have proper feedback based stabilization, so output voltage may ch...
(BASED_HYPHEN)
[uncategorized] ~130-~130: Use a comma before ‘or’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...he setup of the correct device tree file or they will not boot. Check the board spe...
(COMMA_COMPOUND_SENTENCE)
[uncategorized] ~130-~130: When ‘board-specific’ is used as a modifier, it is usually spelled with a hyphen.
Context: ...e file or they will not boot. Check the board specific documentation for details. ## Recover...
(SPECIFIC_HYPHEN)
[typographical] ~142-~142: It seems that a comma is missing.
Context: ...# U-Boot Shell Access If you broke the system you can try to get in this way. You ha...
(IF_COMMA)
[uncategorized] ~191-~191: Use a comma before ‘and’ if it connects two independent clauses (unless they are closely connected and short).
Context: ...boot When something goes terribly wrong and you are not able to boot the system (an...
(COMMA_COMPOUND_SENTENCE)
[style] ~191-~191: As a shorter alternative for ‘able to’, consider using “can not”.
Context: ...n something goes terribly wrong and you are not able to boot the system (and cannot gain access...
(BE_ABLE_TO)
[uncategorized] ~191-~191: This expression is usually spelled with a hyphen.
Context: ...the way to proceed. You will need some Debian based Linux machine where you can mount the f...
(BASED_HYPHEN)
[typographical] ~191-~191: It appears that a comma is missing.
Context: ...an mount the failed SD card. With this procedure you will reinstall the kernel and hardw...
(DURING_THAT_TIME_COMMA)
[formatting] ~191-~191: Insert a comma after ‘cases’: “In most cases,”?
Context: ...tall the kernel and hardware settings. In most cases this should be enough to unbrick the bo...
(IN_MOST_CASES_COMMA)
[uncategorized] ~193-~193: This expression is usually spelled with a hyphen.
Context: ...nd partition(s), respectively (if not a flash based device, it may even be /dev/sdXY, etc...
(BASED_HYPHEN)
[style] ~193-~193: In American English, abbreviations like “etc.” require a period.
Context: ...sed device, it may even be /dev/sdXY, etc). ``` console / # fsck /dev/mmcblkXpY ...
(ETC_PERIOD)
[style] ~244-~244: As an alternative to the over-used intensifier ‘very’, consider replacing this phrase.
Context: ....8.16 dtb ``` If you upgrade from some very old build, you might need to update your bo...
(EN_WEAK_ADJECTIVE)
[misspelling] ~266-~266: This word is normally spelled as one.
Context: ...ors if problems persist. ### Flashing boot loader Sometimes we need to flash boot loader...
(EN_COMPOUNDS_BOOT_LOADER)
[misspelling] ~268-~268: This word is normally spelled as one.
Context: ...boot loader Sometimes we need to flash boot loader from some other Linux. Attach an SD car...
(EN_COMPOUNDS_BOOT_LOADER)
docs/index.md
[grammar] ~28-~28: Consider replacing ‘improving’ with the infinitive form.
Context: ...armbian.com/) where your input can also help us improving this documentation. ### How to report...
(RECOMMEND_YOU)
[uncategorized] ~63-~63: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...rnel development and maintenance with long term support - we provide an extensive [bu...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
🪛 markdownlint-cli2 (0.17.2)
docs/User-Guide_Troubleshooting.md
22-22: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
30-30: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
38-38: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
44-44: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
50-50: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
56-56: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
62-62: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
67-67: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
74-74: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
82-82: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
85-85: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
113-113: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
116-116: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
127-127: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
132-132: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
139-139: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
188-188: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
198-198: Trailing spaces
Expected: 0 or 2; Actual: 1
(MD009, no-trailing-spaces)
198-198: Hard tabs
Column: 1
(MD010, no-hard-tabs)
265-265: Multiple consecutive blank lines
Expected: 1; Actual: 2
(MD012, no-multiple-blanks)
🪛 YAMLlint (1.35.1)
mkdocs.yml
[warning] 112-112: too many spaces before colon
(colons)
[warning] 113-113: too many spaces before colon
(colons)
[warning] 114-114: too many spaces before colon
(colons)
[warning] 115-115: wrong indentation: expected 14 but found 12
(indentation)
[warning] 116-116: too many spaces before colon
(colons)
[warning] 119-119: too many spaces before colon
(colons)
[warning] 121-121: too many spaces before colon
(colons)
[warning] 122-122: too many spaces before colon
(colons)
[warning] 123-123: wrong indentation: expected 14 but found 12
(indentation)
[warning] 123-123: too many spaces before colon
(colons)
[warning] 124-124: too many spaces before colon
(colons)
[warning] 125-125: too many spaces before colon
(colons)
🔇 Additional comments (26)
docs/User-Guide_Troubleshooting.md (5)
38-43: Consistency: Cable Specification
The "Cable" section is clear and practical. No major changes are necessary; however, a brief check for consistent terminology and formatting is recommended.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
38-38: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
51-55: Informative: SD Card Introduction
The introductory text for the SD card section clearly outlines potential risks and failure modes. Ensure that any associated links (if added later) directly support users in testing or troubleshooting their SD cards.
62-66: Clarity: SD Card Size and Speed
The explanation regarding size and speed class is concise and clear. Confirm that any technical terms used are either defined or linked to additional resources for clarity.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
62-62: Multiple consecutive blank lines
Expected: 1; Actual: 2(MD012, no-multiple-blanks)
140-153: U-Boot Shell Access Instructions
The instructions for accessing the U-Boot shell are clear and include concrete command examples. Please verify that these commands are still valid for current hardware revisions.🧰 Tools
🪛 LanguageTool
[typographical] ~142-~142: It seems that a comma is missing.
Context: ...# U-Boot Shell Access If you broke the system you can try to get in this way. You ha...(IF_COMMA)
266-278: Boot Loader Flashing Guidance
The steps for flashing the boot loader are accurately described. Confirm that the terminology and example commands match the latest guidelines for all supported devices.🧰 Tools
🪛 LanguageTool
[misspelling] ~266-~266: This word is normally spelled as one.
Context: ...ors if problems persist. ### Flashing boot loader Sometimes we need to flash boot loader...(EN_COMPOUNDS_BOOT_LOADER)
[misspelling] ~268-~268: This word is normally spelled as one.
Context: ...boot loader Sometimes we need to flash boot loader from some other Linux. Attach an SD car...(EN_COMPOUNDS_BOOT_LOADER)
mkdocs.yml (5)
36-36: New Theme Feature Added: navigation.expand
The addition of "navigation.expand" is a constructive improvement that should enhance the sidebar navigation experience. Please verify that it behaves as expected across all target browsers.
111-112: Navigation Update: Introduction Entry
Updating the "Overview" entry to "Introduction" and mapping it to 'index.md' is consistent with the overall restructuring.🧰 Tools
🪛 YAMLlint (1.35.1)
[warning] 112-112: too many spaces before colon
(colons)
113-113: Navigation Update: Getting Started Entry
The placement of the "Getting Started" entry is appropriate and aligns with the renaming in the respective document.🧰 Tools
🪛 YAMLlint (1.35.1)
[warning] 113-113: too many spaces before colon
(colons)
119-121: Navigation Update: Troubleshooting and Recovery
The consolidation into a "Troubleshooting and Recovery" entry clearly replaces the older "Recovery" section, which helps streamline navigation.🧰 Tools
🪛 YAMLlint (1.35.1)
[warning] 119-119: too many spaces before colon
(colons)
[warning] 121-121: too many spaces before colon
(colons)
122-125: Navigation Update: Appendix Section
Adding an "Appendix" with sub-entries for Changelog, Release Model, and Unit Test Status is a valuable organizational improvement. Please ensure the file paths match the current documentation structure.🧰 Tools
🪛 YAMLlint (1.35.1)
[warning] 122-122: too many spaces before colon
(colons)
[warning] 123-123: wrong indentation: expected 14 but found 12
(indentation)
[warning] 123-123: too many spaces before colon
(colons)
[warning] 124-124: too many spaces before colon
(colons)
[warning] 125-125: too many spaces before colon
(colons)
docs/User-Guide_Getting-Started.md (5)
1-3: Title and Intro Update
Changing the title to "Armbian Getting Started Guide" better reflects the document’s purpose and makes it more approachable for new users.🧰 Tools
🪛 LanguageTool
[style] ~3-~3: Consider using a different verb to strengthen your wording.
Context: ...Started Guide Before you start, please make sure you have: - a proper power supply acco...(MAKE_SURE_ENSURE)
90-124: Download Verification Procedures
The sections on verifying download integrity and authenticity (including checksum and GPG verification) are thorough and well supported with command examples. Verify that the command outputs and key IDs are current before finalizing.
154-198: First Boot and Login Instructions
The step-by-step explanations for booting and logging in are clear and comprehensive. It would be useful to cross-check the command outputs with the latest system behavior to prevent any user confusion.🧰 Tools
🪛 LanguageTool
[misspelling] ~187-~187: Did you mean the verb “log in” instead of the noun ‘login’?
Context: ...he serial console. For SSH, you need to login as root and use the password **1234...(LOG_IN)
249-319: Installation and System Update
The revised installation steps, including instructions for selecting file systems and updating the OS and bootloader, are detailed and well organized. Ensure that any commands or recommended defaults are verified against the latest system versions.🧰 Tools
🪛 LanguageTool
[style] ~251-~251: The phrase ‘in many cases’ is used quite frequently. Consider using a less frequent alternative to set your writing apart.
Context: ...lling it onto your device's hard-drive. In many cases, you probably want to apply some basic ...(IN_MANY_STYLE_CASES)
[uncategorized] ~265-~265: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ...ge, nothing has been installed onto the boards internal drive yet. Using the installer...(AI_HYDRA_LEO_APOSTROPHE_S_XS)
[misspelling] ~265-~265: This word is normally spelled as one.
Context: ...w decide, where you want to install the boot loader and the rest of the system. The install...(EN_COMPOUNDS_BOOT_LOADER)
[grammar] ~280-~280: The word ‘install’ is not a noun.
Context: ... user a sensible default --> Start the install script and follow the lead: armbia...(A_INSTALL)
[uncategorized] ~286-~286: The preposition ‘on’ seems more likely in this position.
Context: ...2/nandsata.png) After you have decided for an option, you can choose between the f...(AI_HYDRA_LEO_REPLACE_FOR_ON)
341-352: Troubleshooting and Bug Reporting
The final section on how to report bugs is concise and provides clear directions. It might be useful to include a direct link to a centralized issue tracker or FAQ section in the future.docs/index.md (11)
5-9: Preface Section Updated
The new "Preface" heading and its supporting text offer a more formal and clear introduction to the documentation. This sets a professional tone for the rest of the material.
11-17: Documentation Structure Explanation
The section explaining how to navigate the documentation is clear and directs users effectively to key sections (Introduction, Getting Started).
26-30: Additional Help Section
The guidance for seeking additional assistance (via the Armbian forum) is friendly and accessible. A minor review for any typographical tweaks (e.g., "improving this documentation") as per static analysis feedback is recommended.🧰 Tools
🪛 LanguageTool
[grammar] ~28-~28: Consider replacing ‘improving’ with the infinitive form.
Context: ...armbian.com/) where your input can also help us improving this documentation. ### How to report...(RECOMMEND_YOU)
31-34: Bug Reporting Instructions
The steps provided for reporting documentation issues are straightforward and include all necessary links.
36-41: Armbian Overview
The "What is Armbian?" section succinctly explains the project’s goals and technological basis. This overview sets a solid context for new users.
42-54: Mermaid Diagram for Armbian Overview
The diagram visually summarizes the relationship between hardware and software components effectively. Verify that its content continues to reflect the current system architecture.
56-72: Key Features Listing
The key advantages of using Armbian are presented clearly. The list is both comprehensive and easy to read, which aids in quick information retrieval.🧰 Tools
🪛 LanguageTool
[uncategorized] ~63-~63: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...rnel development and maintenance with long term support - we provide an extensive [bu...(EN_COMPOUND_ADJECTIVE_INTERNAL)
73-83: Additional Performance Tweaks
The collapsed block for other performance features provides extra insight for advanced users. Confirm that the list remains up to date with the latest feature set.
111-127: Hardware Support Information
This section clearly communicates the varying support levels for different SBCs. The use of interactive buttons is a nice touch—ensure that all links and support criteria are current.
129-132: Images and Sources
A brief and clear section directing users to the main website and GitHub repositories. This is straightforward and effective.
136-154: Software Titles Overview
The overview of available software titles and the inclusion of unit test statuses are well presented. Confirm that all links (including workflow badges) are operational and reflect the latest build status.🧰 Tools
🪛 LanguageTool
[uncategorized] ~147-~147: Possible missing article found.
Context: ...run and optimized for Armbian. Here are few highlights: - Desktops - install deskt...(AI_HYDRA_LEO_MISSING_A)
4 participants
As discussed and requested, here is the PR. Please review and please note that not all content has been rewritten yet.