Repository navigation
Convert the restored articles to Markdown - #188
Merged
Merged
Conversation
Render restored wiki articles written in Markdown exactly like their
converted HTML. Headings carry their existing ID explicitly
({#id}); a missing or duplicate ID fails the build, so rewording a
heading cannot break saved links. Article headings get no Starlight
anchor-link wrapper, and external Markdown links keep
rel="noopener noreferrer". Other pages keep Starlight's defaults.
Add scripts/convert-articles-to-markdown.mjs, which converts an
article's HTML body to Markdown deterministically. It renders every
block with the site's own pipeline and keeps the original HTML where
Markdown would render differently. It also runs on newer wiki
revisions rendered by scripts/migrate-wiki.py.
Convert the 209 restored articles with node scripts/convert-articles-to-markdown.mjs --all. Wording and rendered pages are unchanged: headings keep their IDs and legacy anchors, and HTML remains only where Markdown renders differently, such as figures, code with source IDs, gap markers and complex tables. The three additional historical articles stay HTML, because their receipts cover the HTML.
Keep both test lists in package.json.
Scripts that read the article sources, such as the section repair test and the backup comparison, match a link followed by its "section not recovered" marker as written. Keep that link as HTML; the rendered pages are unchanged.
Keep the 209 restored articles as they are on main (HTML, with the recorded line-break formatting) in migration/restored-articles/. The fidelity gate starts every article's chain there, so the originals stay verifiable against migration/restoration-fidelity.json without pandoc or the recovery data. The directory is a preserved restoration material: check fails when a pull request changes it. A material the base does not have yet may be added by the pull request that adds it to the guard, so this one can be introduced.
Each article is now a checked chain from its preserved restored HTML: accepted HTML edits, at most one Markdown conversion, then accepted Markdown edits. migration/markdown-format.json records each conversion by the hashes of the HTML it replaced and of the Markdown. On every run the gate renders both with the site's own Markdown pipeline and requires the same page, normalizing only what a browser does not show: attribute order, whitespace at line edges and in runs (not inside pre or code), Starlight's dir="auto" on inline code, and Starlight's heading link in its exact form. The HTML must render as itself, and a later change to the recorded Markdown needs a receipt. Receipts record the replaced Markdown and undo to exactly the converted file. The structure rules of an accepted or awaiting edit now apply to the rendered elements, since Markdown adds images, headings, links, autolinks, footnotes, asides and raw HTML without a source tag; the allowlist and locked elements are unchanged, inline code may carry Starlight's dir="auto", and HTML that reaches past the article fails. Articles still in HTML keep the source-level rules as well. The renderer runs only on the package versions it was checked with, and npm run build compares it with the build for every article. The receipts job installs the packages it now needs.
The site applies section repairs and archived templates to the rendered
article (src/components/SourceHistory.astro). A Markdown heading carries
its ID as {#id}, so the section repair check now looks for the target ID
on the target's rendered page and confirms each repair still applies to
the source article's rendered page. Template placements are counted on
the rendered page too, and the tests render the articles first.
Explain that receipts record the replaced Markdown, that accepted edits are checked on the rendered page, how a conversion is recorded and checked, and which differences the conversion check allows.
Give every article heading Starlight's standard anchor link instead of the site's own "#" copy button, which is removed. Headings that stay HTML, including the additional historical articles and headings added from archived templates, get the same markup and link to their existing ID. The link label drops the space articles keep at the end of headings. The link keeps the copy button's size, so headings wrap and take the same space and section anchors stay in place. Search output is unchanged. The converter compares Markdown with the original HTML as the site renders it, so the article files are unchanged.
…/markdown-fidelity
The site now adds Starlight's heading link to every article heading, Markdown and HTML alike. The conversion check compares the two rendered pages with their heading links, so the links must match as well; the normalization stays attribute order, invisible whitespace and dir="auto" on inline code. An HTML article must still render as its source. The heading link is the one thing the site adds there, so that comparison accepts it only in the exact form the site renders for the heading's ID and text, learned from a sample heading; anything else in a wrapper still counts.
|
Important Review skippedToo many files! This PR contains 466 files, which is 366 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. Usage-priced reviews support at most 300 files.
 |
| Check name | Status | Explanation | Resolution |
|---|---|---|---|
| Title check |  |
This assessment has not completed. The check will be retried on the next pre-merge check run. | |
| Description check | |
This assessment has not completed. The check will be retried on the next pre-merge check run. |
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.
migration/markdown-format.json said which Markdown each article was converted to, but a pull request could change an article and set the new hash, so the edit passed as a fresh conversion that needs no receipt. Make the record a preserved restoration material. This pull request adds it, so it is exempt; later pull requests cannot change it without changing the guard.
A review of the gate found ways around it; this closes them. - Parse rendered articles as part of a whole page, inside <main>, not as a fragment. A fragment parse dropped a <body> or <html> start tag, whose attributes (onload, hidden, inert, dir) the browser adds to the page, and a </main> that moves the rest of the page out of <main>. These now fail, and tags that act on the page's own elements are refused outright. - Check the page after its string replacements. The link, section, template, media and heading replacements move from SourceHistory.astro into scripts/lib/article-page.mjs, which the page and the gate both run, so a change the comparison ignores (a line break before a gap marker) can no longer make the page link other text. The link and template patterns now match text only. - Compare each figure as a whole, so a receipt cannot wrap an image in a new link or change its caption. - Code blocks, tables and recovery gap markers change only when the receipt lists them in changed_locked_content, and invisible characters (format characters such as zero-width spaces and bidirectional controls) are added only when it lists them in added_invisible_characters. An awaiting edit names them, and the drafted receipt lists them. - After the build, each built article page must show exactly the checked article, with its IDs unique on the page, and only known page files may exist under src/pages/, so a static page cannot replace an article. - dir="auto" counts as right-to-left for code holding RLM, ALM, RLE, RLO or RLI, and heading text is inserted with function replacements. Each confirmed attack is a regression test, and the self-test re-records two conversions to check they fail.
The receipts job runs the pull request's code with a token, and the gate needs no install script, so npm ci runs with --ignore-scripts there. CONTRIBUTING.md describes what a receipt may now change, the conversion record as a preserved material, and the checks on built pages.
The check compared how often each invisible character occurred, so an edit could take one out in one place and put it into a URL, a number or a word elsewhere. Now every invisible character in a change's accepted text, written out or as a character reference, must be listed in the receipt's added_invisible_characters. The count comparison stays as a backstop.
A pull request could change a template rendering and its hash and so put any HTML into articles, or reword a migration note shown on article pages, without a receipt. Every record under migration/ that pages build on, and recovery-evidence/, is now a preserved material: template renderings and definitions, section and link repairs, alias evidence, articles, navigation, routes, the recovered category and the source formatting. Correcting one needs its own pull request that also changes the guard. The migration notes may only gain notes. Existing notes stay byte for byte, and each new note must be cited by a receipt the pull request adds or changes, so a documentation reviewer approves it with the receipt. A test keeps every file under migration/ classified.
A docs entry elsewhere with slug "wiki/teams/index" and a head script won the article's route, and public/Teams/index.html replaced an old wiki address; Astro only warned. Now the build fails on either warning (scripts/astro-build.mjs), and after it: - every docs entry must keep the route its path gives it, set only known front-matter fields (no head), be Markdown or a known MDX page, and take no old wiki address or alias; - public/ may hold only its known entries and no HTML; - what runs or loads around the content must be the same on every article page, apart from the contents-list scripts. Template renderings may also put in only plain template HTML.
…stably - Invisible characters now include default-ignorable, control (other than tab and line breaks), unassigned, private-use and surrogate code points, so U+17B4, U+180B, U+FFF0 or U+E0080 are flagged. - They are judged by position in the rendered article's decoded text, so a hand-written receipt that splits a character reference across a change boundary cannot move one unlisted. - Code blocks keep their code's ID as their name; tables and gap markers are named by the heading they follow and their number there, so dropping one no longer renames the rest, and each is compared with the text around it, so moving one counts as changing it. - <noscript> and <template> are refused in article content. - record-accepted-edit.mjs fills the receipt's lists from the check's findings, as the receipts job's drafts do.
Explain which migration records are preserved and how a correction goes, how migration notes are added, the new names for locked parts, the wider invisible-character rule, and what the build refuses so that pull requests without article changes are covered too.
The two MDX docs pages run code when the site is built: an import could push a script into every page's head or change the notes article pages show. Both are now preserved materials, which keeps the site as it is. Migration notes: note IDs are unique, so a note cannot stand in for an existing one; a new note has an ID of its own; and every article a new note is shown on needs a receipt in the same pull request that cites it. The gate also fails on duplicate note IDs, and a receipt change may not end inside a character reference the following text completes.
- Code blocks, tables and gap markers are compared together with their section and their place among the locked parts, so two code blocks with the same surroundings cannot trade places unlisted. - public/ allows only certain file types per folder: fonts and their licence, images and the media index, text and JSON. An SVG or XHTML file could be a page of its own. - Template renderings may link outside the site only to GitHub, the one host the archived renderings use. - No docs entry other than the two known MDX pages may hold an import or export statement.
The tests mixed their own approval rule with the repository's receipts, so the first real accepted edit would have failed npm test, and newer tests read live articles, so a wording proposal on Teams, Troubleshooting or the backup script failed it too. The tests now leave out every committed receipt, use their own settings, and read converted fixtures checked against the preserved originals and the conversion record. A test commits a valid receipt for a real article with the repository's own settings, and each review case is a regression test.
Name what the check does not cover (code under src/ and scripts/, and pages that are not restored articles), and describe the MDX pages as preserved materials, the migration note rules, the public file types and how locked parts are compared.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
hiciefte
added a commit
to hiciefte/documentation
that referenced
this pull request
Nov 11, 2026
main converted the restored articles from HTML to Markdown (bisq-network#188). Each article this branch edits is now the converter's output for the branch's edited HTML (scripts/convert-articles-to-markdown.mjs), and renders to the same page as that HTML. The wording change itself is unchanged.
This was referenced Nov 11, 2026
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.
Replaces #184. The restored articles become Markdown wherever the site still looks as designed, so reviewers can edit them in the browser and diffs stay readable.
What changes
## Title {#id}), so rewording a heading can't break links; the build fails on a missing or duplicate ID. The old wiki anchors (#List_of_Teams) stay.#button (accepted after before/after screenshots).migration/restored-articles/.migration/markdown-format.jsonrecords which Markdown file renders the same as each preserved article. Both are preserved materials, and so is every other record article pages are built from (template renderings, repairs, aliases, articles, navigation, routes,recovery-evidence/) and the two MDX pages, which run code at build time. Migration notes may only gain notes with IDs of their own, each cited by a receipt in the same PR for every article it is shown on.scripts/lib/article-page.mjs), parses it as part of a whole page, and compares it with its preserved HTML. Receipt rules apply to that page, so a Markdown image, heading or link, or a<body>or</main>tag, can't get past them.changed_locked_content(named by code ID, or by the heading they follow); invisible and other non-printing characters only if it lists them inadded_invisible_characters.head), unknown page files, unknown entries or HTML inpublic/. Each article page must show exactly what the check saw, with unique IDs and the same scripts around it as every other article page.scripts/convert-articles-to-markdown.mjsconverts newly imported wiki revisions the same way.Checked
npm test(166 tests) and the strictnpm run buildpass, also with the project base path. The tests no longer depend on committed receipts or live article files: they pass with a real receipt committed and with wording proposals open. The check still passes on the HTML articles onmain.check,receiptsor the build. Code undersrc/andscripts/and pages that aren't articles stay outside the check (CONTRIBUTING.md, "Limits"). The PR stays a draft until the review is done.After merge
scripts/lib/render-markdown.mjs; the check stops on any other version.This changes article files, so it needs a documentation reviewer's approval.