Markdown help center

The ledger separates what the audit changed, what was kept on purpose, and what has not run in production yet.

1. Fixed in the templates

   • The sidebar hid half of the biggest category The desktop sidebar animated category collapse with max-h-[600px] + overflow-hidden. The largest category's list was more than twice the height of the cap, so more than half of its links were unreachable from the sidebar. The mobile drawer used a much larger cap and was fine, so nobody testing on a phone saw it, and on desktop the list simply looked complete.
   • Search that missed what people typed Substring match on title and description only. Consequences, each verified in the code:
   • Order ties resolved by filesystem order Articles sorted by order only. The corpus had three pairs sharing an order (2, 5, 27). JavaScript's sort is stable, so ties kept readdir order — which is alphabetical on APFS, creation order on some Linux filesystems, and not guaranteed anywhere. The same deploy could list two articles in a different order on a different build machine.
   • Related links that vanish silently related entries were resolved by slug across every category, and unresolved ones were dropped without a warning anywhere. Renaming an article broke every inbound related reference invisibly. Slugs were also only unique per folder, so a bare reference could resolve to the wrong category's article.
   • The corpus re-parsed several times per page Six loader functions each walked the tree. One article render called them from the layout, the page, generateMetadata and the related resolver — around four full parses of every file per page, and again per locale in generateStaticParams.
   Show 9 moreShow fewer

   • "Popular articles" that were not The landing page showed getAllHelpArticles().slice(0, 6) under the heading Popular articles: the first six files of the first folder, by order.
   • English chrome on a three-locale site The site rendered Polish and German everywhere except the help center, whose header, sidebar, buttons, category labels and "Updated {en-US date}" were literals — in an app with a working i18n dictionary that the same component tree used for its footer.
   • order: 0 sorted last (frontMatter.order as number) || 999 — zero is falsy. Minor, but the kind of thing that wastes an afternoon.
   • Invalid structured data when a date was missing dateModified: article.updatedAt emitted "" for articles without a date. JSON-LD was also interpolated unescaped; a </script> in a title would have ended the block.
   • Dead code A HelpSearchBar component rendering a disabled input labelled "Soon", and a getHelpArticlesByTag function — both exported, neither imported anywhere.
   • Frontmatter that lied without consequence slug and category in frontmatter were ignored by the loader (filename and folder win). Nothing detected a mismatch. The corpus had none — but the next copy-pasted file would.
   • A frontmatter parser that dropped multi-line values The earlier implementation parsed frontmatter line by line: key: value, JSON-parse anything in [...]. Prettier wraps arrays past 100 columns onto several lines, and every such value read as empty, silently. Found in the earlier implementation hours after the audit, when a new article's related list came out blank: roughly a quarter of the content files across every markdown content type sharing the parser had an empty list field in production, related and tags among them, including cards that had rendering code and had never once rendered.
   • Tags keyed by spelling The earlier implementation's only tag lookup, getHelpArticlesByTag, matched the exact string (tags.includes(tag)), and nothing ever normalised a tag for a URL. Run over the corpus, the 0.2.0 validator found, invisible on the site:
   • What validation found in the real corpus Running the shipped validator over the earlier implementation's content on audit day: 3 order ties, 0 unresolved references, 0 slug mismatches, and 37 of 65 updatedAt values identical (the import date). None of these were visible on the site. The date problem is a content problem; deriving dates from git is in extensions.md.