Skip to content

Docs: escape the <user> and <account> placeholders in deployment.md's web UI paths - #625

Merged
schmitch merged 1 commit into
mainfrom
schmitch/elegant-brown-nn3aot
Oct 28, 2026
Merged

schmitch merged 1 commit into
mainfrom
schmitch/elegant-brown-nn3aot

Conversation

@schmitch

@schmitch schmitch commented Oct 28, 2026 •

Copy link
Copy Markdown
Member

Fixes #624

Problem

Three web UI paths in docs/deployment.md used bare <user> and <account> placeholders inside bold text, outside a code span. Markdown read them as HTML tags, so GitHub's sanitizer dropped them and the page showed "Admin → Users → → Deactivate". mdBook, which builds the docs site in #623, dropped them too and warned about an unclosed HTML tag <user> while exiting Strong.

Change

  • docs/deployment.md: each placeholder is escaped with a backslash (\<user>, \<account>). GitHub and pulldown-cmark both render that as the literal text <user>. A code span would not fit, because the rest of the bold UI path is plain text. The affected lines:
    • Deactivating users: Admin → Users → <user> → Deactivate
    • Trusted-header authentication: Admin → Users → <user> → Tokens and Admin → Service accounts → <account>
  • docs/changes/2.1.1/624.docs.md: the changelog fragment.

CHANGELOG.md has the same problem in two 2.0.0 entries (<user>, <name>). It stays unchanged because a change never edits it.

Verification

  • cargo xtask changelog --check: passes.
  • cargo xtask docs only exists on Docs: publish the guides as a GitHub Pages site with navigation and search, built with mdBook by cargo xtask docs #623's branch, so I applied this change on top of that branch:
    • cargo xtask docs --check passes: "12 page(s) of the site, every link resolves."
    • cargo xtask docs with mdBook 0.5.4: the three unclosed HTML tag … found in deployment.md while exiting Strong warnings are gone. The two warnings left are for changelog.md, which this PR deliberately leaves alone. In deployment.html the paths now read Admin → Users → <user> → Deactivate, Admin → Users → <user> → Tokens and Admin → Service accounts → <account>.

🤖 Generated with Claude Code

https://claude.ai/code/session_012e6DJXh2a4iuE7x7K94GNJ

Three UI paths in docs/deployment.md wrote their placeholders bare in
bold text: **Admin → Users → <user> → Deactivate**, **Admin → Users →
<user> → Tokens** and **Admin → Service accounts → <account>**.
Markdown reads <user> and <account> as HTML tags, so GitHub's sanitizer
dropped them ("Admin → Users → → Deactivate") and mdBook dropped them
too, warning about an unclosed HTML tag while exiting Strong.

A backslash escapes each one (\<user>, \<account>), which GitHub and
pulldown-cmark both render as the literal text. A code span would not
fit, since the rest of each path is plain bold text. CHANGELOG.md has
the same problem in two 2.0.0 entries but stays as it is: a change never
edits it.

Fixes #624

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012e6DJXh2a4iuE7x7K94GNJ
@schmitch
schmitch added this pull request to the merge queue Oct 28, 2026
Merged via the queue into main with commit 982599c Oct 28, 2026
17 checks passed
@schmitch
schmitch deleted the schmitch/elegant-brown-nn3aot branch October 28, 2026 12:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Docs: deployment.md's UI paths lose their placeholders ("Admin → Users → → Deactivate"), because <user> and <account> render as HTML tags

2 participants