mirror of
https://github.com/coder/coder.git
synced 2026-10-16 14:48:56 +08:00
Ian Evans
21c1abe9ad
Reformats every Markdown page under `docs/install` to the [one-sentence-per-line convention](https://github.com/coder/coder/blob/main/docs/.style/style-guide/formatting.md#one-sentence-per-line). Addresses DOCS-668. This is a source-layout change only: 28 of the 36 pages change, and rendered HTML is identical for all of them except three wording fixes. Three pre-existing em dashes sat on reflowed lines, which `lint/emdash` flags as new, so they're rewritten with commas or a sentence break (`operate/upgrade/esr-2.24-2.29-upgrade.md`, `operate/upgrade/best-practices.md`). Front matter, fenced code, tables, HTML blocks, and headings are untouched. `Coder.OneSentencePerLine` is not enabled for `docs/install` in `.vale.ini`: the 39 remaining findings are all table rows or code, which the guide puts out of scope, and enabling the rule would break the zero-baseline doctrine. <details> <summary>Implementation and verification notes</summary> **Approach.** A throwaway script reflowed each paragraph. Bullet items, numbered entries, and blockquote lines (including `> [!NOTE]` callouts) are each their own paragraph; extra sentences in a list item continue on indented lines, matching `docs/.style/content-guidelines.md`. Sentence breaks are never inserted inside inline code, link text, URLs, or HTML tags, and abbreviations such as `e.g.` and `etc.` don't count as sentence ends. Images that started their own source line stay on their own line. The script is idempotent: a second pass produces no changes. **Merge with main.** `main` restructured `docs/install` into plan, prepare, server, validate, and operate sections after this branch was cut. The merge takes `main`'s tree and re-runs the reflow over every page now under `docs/install`, so the branch diff against `main` is reflow only. `releases/index.md` and `releases/feature-stages.md` moved out of `docs/install` on `main` and are no longer in scope. **Verification.** - Rendered every page with `marked` from `main` and from this branch and compared normalized HTML: identical except the three em-dash rewrites. - Vale with `Coder.OneSentencePerLine` forced on for `docs/install`: 277 findings on `main`, 39 on this branch, all in table rows or fenced code. - A broader sweep for mid-line sentence boundaries and for false splits (lines starting lowercase, lines ending in an abbreviation) found no prose hits. - `markdownlint-cli2`, `markdown-table-formatter --check`, `make lint/emdash`, and `make pre-commit-light` pass. </details> --- *Generated by Coder Agents on behalf of @ianjevans.*