Skip to content

docs: fix broken anchors, extra H1s and an unclosed code span - #8149

Draft
nickvigilante wants to merge 3 commits into
coder:mainfrom
nickvigilante:vigilante/docs-content-fixes
Draft

nickvigilante wants to merge 3 commits into
coder:mainfrom
nickvigilante:vigilante/docs-content-fixes

Conversation

@nickvigilante

Copy link
Copy Markdown

There is no issue for this; it is a small docs-only fix. coder.com is moving code-server's docs at coder.com/docs/code-server onto the same renderer as the Coder docs, which builds them straight from this repository's docs/ folder. Checking the pages for that move turned up a few defects that show on GitHub as well. Every file name, and so every URL, stays the same.

Broken anchors. Each of these three links went to a heading that doesn't exist, so it landed at the top of the page:

  • docs/guide.md: the Let's Encrypt link pointed to #let-encrypt. It now points to #using-lets-encrypt-with-caddy.
  • docs/install.md: the Termux link pointed to termux.md#installation. It now points to termux.md#install.
  • docs/ipad.md: the ctrl+c workaround link pointed to #ctrl-c-workaround. It now points to the "Workaround for issue with ctrl+c…" heading.

Unclosed code span. In docs/guide.md, step 3 of the Svelte proxy example never closed its backtick, so the rest of the line rendered as code.

One H1 per page. A second H1 reads as a second page title to screen readers and search engines.

  • docs/android.md had one H1 for each install method. It now has the title "Running code-server on Android", with UserLAnd and Nix-on-Droid as sections. Its description in docs/manifest.json now names both methods.
  • docs/helm.md: "Extra Containers" is now an H2, alongside Configuration and Values.
  • docs/CODE_OF_CONDUCT.md repeated its title below the doctoc title. The other doctoc pages (FAQ, guide, install and the rest) use the doctoc title as their only H1, so this page now does too. The doctoc table of contents no longer nests its sections under the removed heading, and re-running pnpm run doctoc leaves it as it is.

Search descriptions. The old coder.com renderer had hand-written search descriptions for the home, install, setup guide and FAQ pages. The new renderer reads a page's description from its front matter and otherwise falls back to the shorter description in manifest.json, so this PR adds those four descriptions as YAML front matter, as they were published (with "a iPad" corrected to "an iPad"). On GitHub, front matter shows as a small table at the top of the file. A question for the maintainers: is that OK for these four pages? If you'd rather not have front matter in the docs, I'll drop that commit. The old site also had longer SEO <title>s for these pages, such as "Install code-server: OS Instructions for VS Code". The new renderer would show a front-matter title as the visible page heading too, so I've left the titles out of this PR.

Testing: prettier --check (3.9.4) passes on every changed file, and running doctoc the way ci/dev/doctoc.sh does changes nothing. The new renderer's strict sync passes with all 19 pages. Each page renders with one title, takes its description from the front matter or the manifest, and every in-page and cross-page anchor resolves.


🤖 Built with AI assistance.

The guide linked Let's Encrypt to #let-encrypt, the install page linked
Termux to #installation and the iPad page linked its ctrl+c workaround to
#ctrl-c-workaround; none of those headings exist, so each link landed at
the top of the page. Point them at the headings they mean. The Svelte
proxy step in the guide also opened a code span it never closed, which
rendered the rest of the line as code.

Assisted-by: AI
The Android page had one H1 per install method, the Helm page made Extra
Containers an H1 beside its configuration sections, and the code of
conduct repeated its title below the doctoc title. A second H1 reads as a
second page title to screen readers and search engines, and a docs site
that uses the first H1 as the page title leaves the others as stray
titles in the body.

Android now has an Android title with one section per method, and its
manifest description names both methods. Extra Containers is a section of
the Helm page. The code of conduct keeps the doctoc title, as the other
doctoc pages do, and its table of contents loses the nesting under the
removed heading.

Assisted-by: AI
coder.com's previous code-server docs renderer carried hand-written
search descriptions for the home, install, setup guide and FAQ pages.
The new renderer reads a page's description from its front matter and
falls back to the shorter manifest description, so those four would
otherwise lose them. Add them as front matter, as they were published
(with "a iPad" corrected). Prettier and doctoc both leave the front
matter in place.

Assisted-by: AI

This branch has not been deployed

No deployments
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.

1 participant