Repository navigation
docs: fix broken anchors, extra H1s and an unclosed code span - #8149
Draft
nickvigilante wants to merge 3 commits into
Draft
nickvigilante wants to merge 3 commits into
nickvigilante wants to merge 3 commits into
Conversation
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
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
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.
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 totermux.md#installation. It now points totermux.md#install.docs/ipad.md: the ctrl+c workaround link pointed to#ctrl-c-workaround. It now points to the "Workaround for issue withctrl+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.mdhad 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 indocs/manifest.jsonnow names both methods.docs/helm.md: "Extra Containers" is now an H2, alongside Configuration and Values.docs/CODE_OF_CONDUCT.mdrepeated 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-runningpnpm run doctocleaves 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
descriptionfrom its front matter and otherwise falls back to the shorter description inmanifest.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-mattertitleas 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 runningdoctocthe wayci/dev/doctoc.shdoes 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.