From a25de993df35f7016cedda197818f90ce77373d7 Mon Sep 17 00:00:00 2001
From: Yuriy Andamasov <yuriy@vyos.io>
Date: Thu, 7 May 2026 11:28:48 +0300
Subject: docs(claude-md): fix Markdown rendering + clarify rst- prefix wording
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three rendering/clarity fixes flagged by Copilot review across the
post-flip CLAUDE.md trio (#1902/#1906/#1907):

1. **Triple-backtick examples in single-backtick code spans broke
   Markdown rendering.** The MyST fence example
   ```{cfgcmd} set system ...``` was wrapped in a single-backtick
   span, where the inner triple backticks confuse the parser. Switch
   to a four-backtick code span so the literal fence renders cleanly.
   Same fix applied to the "Configuration page structure" bullet.

2. **RST inline-literal example used confusing nested backticks.** The
   line "Inline code: \`\`\`\`command\`\`\`\`" parsed but
   was hard to read. Replace with a plain explanation:
   "Inline code: use double backticks (\`\`command\`\`)".

3. **Clarify that the `rst-` override prefix attaches to the basename,
   not the path stem.** The previous wording `docs/rst-<page>.rst`
   could be misread as a top-level prefix. The actual behavior in
   `scripts/swap_sources.py` is: for a page at
   `docs/automation/cloud-init.md`, the override file lives at
   `docs/automation/rst-cloud-init.rst` (basename-prefixed sibling).
   Spell that out with a concrete example.

Same fixes applied symmetrically across [#1902](https://github.com/vyos/vyos-documentation/pull/1902) (current),
[#1906](https://github.com/vyos/vyos-documentation/pull/1906) (circinus), and [#1907](https://github.com/vyos/vyos-documentation/pull/1907) (sagitta) — all three worktrees
back to byte-identical (md5 `d1ceaddc...`).

\xf0\x9f\xa4\x96 Generated by [robots](https://vyos.io)
---
 CLAUDE.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 7b4bb963..c921033c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -106,7 +106,7 @@ For pages that have NOT been migrated:
 - `docs/<page>.rst` — original RST, no `rst-` prefix, no MD sibling.
 
 **Editing rules:**
-- Migrated page (has `<page>.md`): edit the `.md`. Don't touch `rst-<page>.rst` unless you're maintaining a parallel RST version that someone has flagged in `_rst_overrides.txt`.
+- Migrated page (has `<page>.md`): edit the `.md`. Don't touch the `rst-`-prefixed sibling unless you're maintaining a parallel RST version that someone has flagged in `_rst_overrides.txt`.
 - Non-migrated page (RST-only): edit the `.rst`.
 - New page: write it as `.md` from the start. The `md-` prefix that earlier MyST migration commits used is gone — never add it.
 
@@ -114,7 +114,7 @@ Running `make html` runs the swap automatically (it's a no-op when the override
 
 ### Command directives
 
-`.. cfgcmd::`, `.. opcmd::`, and `.. cmdinclude::` are the VyOS-specific Sphinx directives in RST. They are tracked for command coverage — do **not** convert them to plain `.. code-block::`. In MyST the same directives are written as fenced blocks: ` ```{cfgcmd} set system ... ` (enabled by `myst_fence_as_directive`). The MyST include directive is named `cmdincludemd` (not `cmdinclude`) so that template parsing follows MyST rules in MD pages and RST rules in RST pages — pick `cmdinclude` in `.rst`, `cmdincludemd` in `.md`.
+`.. cfgcmd::`, `.. opcmd::`, and `.. cmdinclude::` are the VyOS-specific Sphinx directives in RST. They are tracked for command coverage — do **not** convert them to plain `.. code-block::`. In MyST the same directives are written as fenced blocks: ```` ```{cfgcmd} set system ... ```` (enabled by `myst_fence_as_directive`). The MyST include directive is named `cmdincludemd` (not `cmdinclude`) so that template parsing follows MyST rules in MD pages and RST rules in RST pages — pick `cmdinclude` in `.rst`, `cmdincludemd` in `.md`.
 
 ## Source conventions
 
@@ -137,7 +137,7 @@ The first heading in every RST file uses `#` overline+underline. Field lists (e.
 - American English.
 - Indent with 2 spaces.
 - Blank lines around headings.
-- Inline code: `` ``command`` ``.
+- Inline code: use double backticks (`\`\`command\`\``).
 
 ### IP addresses (linter-enforced)
 
@@ -174,7 +174,7 @@ Markers must always come in pairs. Indentation may match the surrounding directi
 ### Configuration page structure
 
 1. **Theory** — what it is, when to use it, relevant RFCs.
-2. **Configuration** — all CLI options as `.. cfgcmd::` (RST) or ` ```{cfgcmd} ` (MD).
+2. **Configuration** — all CLI options as `.. cfgcmd::` (RST) or ```` ```{cfgcmd} ```` (MD).
 3. **Examples** — practical configurations with topology diagrams.
 4. **Known issues** — problems and workarounds.
 5. **Debugging** — log collection, `show` commands, state indicators.
-- 
cgit v1.2.3