docs(common): fix broken uart/ssh links + rename screenless → headless in cubie#1917
Merged
Milir-Radxa merged 4 commits intoJul 8, 2026
Merged
Conversation
added 4 commits
July 8, 2026 14:11
…-system partials The shared common partials `_screenless.mdx` and `_use_system.mdx` link to `./uart_login` / `./ssh_remote` (and `../system-config/uart_login` / `ssh_login`), but the actual page slugs are `uart-login` and `ssh-login` (with hyphens), so every cross-reference to the serial-console and SSH pages returns 404 on docs.radxa.com. Both partials are only consumed by cubie a5e and cubie a7s, and those two products are the only ones whose local UART/SSH pages use the `uart-login` / `ssh-login` slugs, so the rename is safe for the current set of importers. Update both partials in Chinese and English to keep the docs in sync.
…ess' in EN The English pages for cubie a5e and a7s render the '无屏模式' section as 'Screenless Mode', which is not the conventional term in the SBC / Linux-on-arm world. ROCK 5 / ROCK 4 / ROCK 3 / Zero / CM3 / template-sbc all already use 'Headless Mode' for the same concept. Update the EN titles, headings and first-sentence wording to use 'Headless' / 'Headless Mode' so cubie's terminology matches the rest of the docs. Leave the slug and filename (`screenless` /`screenless.md`) alone for now — renaming those would also require a URL redirect and a follow-up PR.
…ss.mdx Follow up on the 'screenless → headless' terminology cleanup. The cubie shared partial lived at `common/radxa-os/system-config/_screenless.mdx`, which is the only place outside of CN/EN headless pages still using the 'screenless' term. Rename it to `_headless.mdx` so the partial file matches the rest of the docs (rock5/rock4/rock3/zero/cm3/template all already use `_headless.mdx`). Update the frontmatter `imports_resolve_to` and the `import … from …` statement in the four cubie a5e / a7s wrapper files (CN + EN) to point to the new file. Note: this leaves us with two partials called `_headless.mdx` — `docs/common/radxa-os/_headless.mdx` (rock5/zero/etc, concise, uses props) and `docs/common/radxa-os/system-config/_headless.mdx` (cubie, detailed with before.txt/config.txt walkthrough). They have different content shapes and merging them is out of scope here. Page slug `screenless` and the `screenless.md` wrappers are intentionally unchanged — renaming those would break published URLs and needs a separate redirect-based PR.
Follow up on the partial rename in the previous commit. The actual
published pages lived at `cubie/{a5e,a7s}/system-config/screenless.md`,
so rename those wrappers too so the page slug matches the partial and
the rest of the docs.
Update the only remaining internal link to the old slug
(`_use_system.mdx`, both CN and EN) to point at `system-config/headless`.
Note: this changes the published URL of `/cubie/a5e/system-config/screenless`
→ `/cubie/a5e/system-config/headless` (same for a7s). No redirect is
added — this matches the existing repo convention used for previous
file renames (e.g. `docs/rockpi/rocks0 → rockpis0`), where URLs
simply change on rename.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
背景
https://docs.radxa.com/cubie/a5e/system-config/screenless页面里有两处跳转链接点击后是 404：串口登录→/cubie/a5e/system-config/uart_loginSSH 远程（出现两次，有线网络 / 无线网络两段各一处）→/cubie/a5e/system-config/ssh_remote实际页面 slug 是
uart-login/ssh-login（中划线），但 partial 里写成了下划线的uart_login/ssh_remote。排查时发现另一个共享 partial
common/radxa-os/install-system/_use_system.mdx（也是只有 a5e / a7s 引用）也命中同样的下划线/中划线错位，按要求一并合到本 PR 修。之后 Tom 又指出
screenless在英文里不是行业标准说法——SBC / Linux-on-arm 圈子通常用headless。这条线已经在 ROCK 5 / ROCK 4 / ROCK 3 / Zero / CM3 / template-sbc 上跑通（这些产品早就用_headless.mdx+# Headless Mode+ slugheadless），Cubie 这边是异类。所以又顺手把 cubie a5e / a7s 的英文翻译统一成Headless，并把 cubie 自己的 partial 文件从_screenless.mdx改名成_headless.mdx。最后 Tom 又要求页面文件
screenless.md也改成headless.md——这会改已发布的 URL，但与仓库此前的 rename 约定一致（参考docs/rockpi/rocks0 → rockpis0这次 PR，URL 直接换、不加 redirect），所以本 PR 沿用同一约定。修改
只动
commonpartial + cubie 自己的 wrapper，中英文同步范围按改动语义自然延伸：docs/common/radxa-os/system-config/_screenless.mdx→_headless.mdx（CN，rename）i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/system-config/_screenless.mdx→_headless.mdx（EN，rename）docs/common/radxa-os/install-system/_use_system.mdx（CN）i18n/en/docusaurus-plugin-content-docs/current/common/radxa-os/install-system/_use_system.mdx（EN）docs/cubie/a5e/system-config/screenless.md→headless.md（CN wrapper 文件 rename）docs/cubie/a7s/system-config/screenless.md→headless.md（CN wrapper 文件 rename）i18n/en/docusaurus-plugin-content-docs/current/cubie/a5e/system-config/screenless.md→headless.md（EN wrapper 文件 rename）i18n/en/docusaurus-plugin-content-docs/current/cubie/a7s/system-config/screenless.md→headless.md（EN wrapper 文件 rename）具体改动：
_screenless.mdx→_headless.mdxCN/EN × 3./uart_login、./ssh_remote./uart-login、./ssh-login_use_system.mdxCN/EN × 1../system-config/uart_login、../system-config/ssh_login../system-config/uart-login、../system-config/ssh-login_use_system.mdxCN/EN × 1../system-config/screenless../system-config/headless_headless.mdxEN × 1Screenless mode refers to …Headless mode refers to …_use_system.mdxEN × 1### Display-less Mode/Display-less mode### Headless Mode/Headless mode# Screenless Mode# Headless Mode# Headless mode（小写）# Headless Mode（与其他产品线一致）_screenless.mdximport 路径_headless.mdximport 路径screenless.mdheadless.md（重命名）_screenless.mdx_headless.mdx（重命名）CN 的"无屏模式"本来就是中文里通顺且准确的写法，没有需要改的对齐内容，所以 EN 翻译这一类是有意的 EN-only，CN 不动。
总计 8 文件 / +20 -20 / 4 commit。
影响范围
仅 cubie-a5e / cubie-a7s 的页面跳转、EN 标题/正文、partial 文件名、页面文件名：
/cubie/a5e/system-config/screenless、/cubie/a7s/system-config/screenless（不再有效，会 404）/cubie/a5e/system-config/headless、/cubie/a7s/system-config/headless不改其他产品，不改 partial 内部中文文本。
为什么这个改法是安全的
_screenless.mdx/_use_system.mdx都只被 cubie-a5e 和 cubie-a7s 引用，且这两个产品的本地页面 slug 恰好就是uart-login/ssh-login。相对链接./uart-login在 Docusaurus 里按引用方所在目录解析（不是 partial 自己所在目录），_auto_login.mdx → ./rsetup是个现成的成功先例。b18dd8ee1 docs: 移除 linkr-kvm 中文教程中的 KVM 表述，引入瑞莎灵控产品名这类既有 single-language PR 的写法。cubie/{a5e,a7s}/system-config/和common/radxa-os/system-config/这两个原本 cubie 独占的子目录下；改完后 cubie 的 wrapper 直接 import/指向新名字的 partial/页面，没有其他产品受影响。docs/rockpi/rocks0 → rockpis0（commita0e26903a）那次重命名的处理方式一致——直接换 URL，不在旧路径保留 redirect 文件。备注
uart-debug/ssh-remote，dragon-q6a / q8b / e20c~e54c 也是，orion-o6 / o6n 用uart/ssh）。这次 partial 只服务 a5e / a7s 是因为这两个产品命名恰好匹配；以后想给其他产品也接headlesspartial，得先帮那些产品改页面 slug 或把 partial 改成参数化。_headless.mdx的 partial：旧的docs/common/radxa-os/_headless.mdx（rock5/zero 等用，精简，用 props）和新的docs/common/radxa-os/system-config/_headless.mdx（cubie 用，详细，含 before.txt/config.txt）。两者内容结构不同，没合并。如果后续想合并，是另一个独立话题。