Repository navigation
Catch more import failures in the docs checker; document diagnosing remote checks - #12
Conversation
…emote checks check.mjs now reports empty link destinations, images inside links and bullets that start with an ordered marker, which FrontLit's import rejects. It no longer flags indented code fences (for example inside list items), which the import accepts. Add guidance for keeping an older docs version alongside the new one and for diagnosing a failed remote check that stops at the first error or has no annotation. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7de9f81d6b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const line = i + 1 + offset; | ||
| const open = text.match(/^\s{0,3}(`{3,}|~{3,})(.*)$/); | ||
| // A fence may be indented, e.g. inside a list item; its content is literal like any other fence. | ||
| const open = text.match(/^\s*(`{3,}|~{3,})(.*)$/); |
There was a problem hiding this comment.
When a page has a four-space-indented literal triple-backtick line outside a list, Markdown treats it as indented code, but this regex treats it as a fence and skips lines through the next matching marker. An unindented <div> between those lines is therefore missed locally even though it remains outside the code block and can fail remote validation. Keep the three-space limit unless the extra indentation is known to come from a list.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 2a28fe2. Fence recognition now follows the enclosing list item's content column: outside a list, four or more spaces start an indented code block, so a fence-like line there is literal and the prose after it is still checked. Fences keep any indentation inside list items, and on pages with rich blocks, which are parsed with MDX rules where indentation is layout. Tests cover both cases.
| if (/^\s*[-*+]\s+\d+[.)]\s/.test(text)) | ||
| report(file, line, "INVALID_DOCUMENT", 'A bullet that starts with an ordered marker ("- 1. text") is rejected; use an ordered list ("1. text").'); |
There was a problem hiding this comment.
When a page uses a standard four-space-indented code block to show a Markdown example such as - 1. text, this check reports INVALID_DOCUMENT even though the line is code, not a bullet. That makes the local checker reject content the Markdown parser accepts; skip indented-code content when applying this rule.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 2a28fe2. Lines inside an indented code block (plain Markdown pages, four spaces past the list or margin, after a blank line) are now skipped by all prose checks, including the list-marker rule. On pages with rich blocks indentation is layout under MDX rules, so indented lines there are still checked. Tests cover both cases.
The remote check rejects any list item that starts with another list marker (- 1., - -, 1. -, 1. 1., - 1)), not only bullets with an ordered marker. A closing fence may be indented at most 3 spaces more than its opening fence, so deeper fence-like lines stay fence content. Reword the remote-check guidance: import-blocking errors hide the rest, warnings are reported together. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Outside a list item, four spaces of indentation start an indented code block, so a fence-like line there no longer opens a fence and list-marker or HTML checks skip its content. Fences keep any indentation inside list items and on pages with rich blocks, which are parsed with MDX rules where indentation is layout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Why
While porting a ~60-page docs site, the bundled checker passed pages that FrontLit's pull request check then rejected, and flagged one valid construct. The remote check also stops at the first error, so reaching a green check took several rounds, one of which had no file or line to go on.
Checker (
scripts/check.mjs)New errors, each confirmed against the remote check:
[text]()(remote:UNSAFE_URL).[](url)such as a badge (remote:UNSUPPORTED_NODE).- 1. text,- 1) text,- - text,1. - text,1. 1. text, top-level or nested (remote:INVALID_DOCUMENT, with no file or line). Each variant was checked separately;- **(1) Name**: …passes.Fixed false positive: code fences were only recognised with up to 3 spaces of indentation, so a fence inside a list item had its contents (for example
<name>) reported as HTML. A fence indented to sit in a list item is accepted by the remote check (verified with a 4-space fence), so fences may now be indented. A closing fence may be indented at most 3 spaces more than its opening fence, as in CommonMark, so deeper fence-like lines inside a fence stay content.check.test.mjscovers each of these, plus non-cases (- **(1) Name**,1 - 3,-1).Guidance
format.md: the three new unsupported constructs, with replacements, and the indented-fence note.porting.md: conversion rows for badges, empty links and nested list markers; a section on keeping an older version of the docs alongside the new one (first folder is the section,slugis independent of the file path,nav_titlefor repeated labels); a section on diagnosing a failed remote check (an import-blocking error fails the whole check and hides the rest; bisecting when there is no annotation;EXTERNAL_MEDIAis informational).SKILL.md: points to the new section.All new text and test fixtures are project-neutral.
Not changed
Existing examples in
format.mdandporting.mdstill use one product's name. Left alone to keep this PR focused.Tests
node plugins/frontlit/skills/frontlit-docs/scripts/check.test.mjsand the other CI steps pass locally. The checker reports no new problems on two real docs folders (17 and 158 pages) that pass the remote check.🤖 Generated with Claude Code