test: verify the docs workflow catches a broken anchor - #29
Closed
jayteemoney wants to merge 5 commits into
Closed
Conversation
Adds .github/workflows/docs.yml, running on PRs that touch markdown: 1. markdownlint-cli2, config in .markdownlint-cli2.jsonc, tuned to this repo's existing prose rather than the other way around (long discursive paragraphs, hand-aligned tables, numbered subsection headings, glossary.md's flat H1-then-H3 definition-list structure). 2. Internal link/anchor checking via lychee, run offline so it only validates relative file links and in-repo heading anchors — this is the job that blocks a PR. 3. Prettier for markdown formatting (.prettierrc.json), checked in a separate job. External link checking runs on its own schedule (weekly cron + workflow_dispatch) and never fails the build: rate limits and transient 5xx on third-party hosts fail builds for reasons unrelated to the PR under review, so external link health is treated as a fact about the internet's uptime rather than the PR's correctness. Actions are pinned to commit SHAs, not mutable tags. Ran `prettier --write` once across the existing docs to get the format check to a passing baseline. That diff is purely mechanical — table column alignment and `*emphasis*` -> `_emphasis_` marker style, both things Prettier's markdown formatter has no toggle to preserve — no prose was reworded. Two markdownlint-only fixes are included for the same reason: wrapping two bare emails in angle brackets (CODE_OF_CONDUCT.md, SECURITY.md) and collapsing accidental double blank lines in CODE_OF_CONDUCT.md's Contributor-Covenant boilerplate.
Addresses review feedback on #28: - Fixed the blocking bug: README.md's "an open issue" link used the GitHub-relative-URL trick (../../issues), which renders correctly on github.com but isn't a real filesystem path. link-check-internal runs --offline and resolves relative links against the filesystem, so this would have failed on the very first PR after merge. Changed to the absolute https://github.com/StelFlow-labs/StelFlow/issues, which also moves it into the (non-blocking) external-link job where a link to our own issues page belongs. - Dropped Prettier entirely: removed the format job from docs.yml, .prettierrc.json, .prettierignore, the two format scripts and the prettier devDependency from package.json, and reverted the formatting sweep across the 11 docs back to their pristine content. Measured on main with default rules: MD060 (table style) fires 94 times and Prettier's machine-alignment makes it fire 0 — so the PR was disabling a rule to protect a style and then removing that style in the same commit. Issue #14 said no content rewrites for exactly this reason. markdownlint-cli2 already catches the two real defects that existed (bare emails, double blank lines) — those two fixes are kept, on CODE_OF_CONDUCT.md and SECURITY.md, since they're genuine issues, not Prettier's doing. package.json and pnpm-lock.yaml stay for markdownlint-cli2. - Fixed three config comments that stated things that weren't true: lychee.toml's accept list comment claimed to be "empty" directly above a non-empty list; its remap comment described anchor-checking behaviour that belongs to include_fragments instead, and claimed a broken-anchor demo had already happened when it hadn't; docs.yml's internal link-check comment invented a --scheme flag that isn't in the args (--offline is what does that work). - Removed MD033 and MD053 from .markdownlint-cli2.jsonc — both fire zero times on this repo in every state, so disabling them protects against nothing. Rewrote MD060 and MD040's comments to describe what's actually true post-Prettier-removal (compact tables measured at 94 hits, and specifically concepts.md's six formula blocks for MD040).
The revert kept these files as Prettier left them because they also carried genuine markdownlint fixes. Only eight lines are real: six MD012 blank-line collapses and one MD034 email wrap in CODE_OF_CONDUCT.md, one MD034 wrap in SECURITY.md. Reverted the rest — the 1) to 1. ordered-list rewrite across the Contributor Covenant boilerplate, and SECURITY.md's table alignment and emphasis-marker change. No markdownlint rule fires on any of those, and with Prettier gone nothing enforces or reverts them. SECURITY.md had ended up with the only padded table in the repo, which contradicted .markdownlint-cli2.jsonc's own MD060 comment. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01K4KmSPBuq484Zt65qsK177
The config never parsed. lychee rejects an unknown or wrongly-typed field outright, so link-check-internal exited 3 on a config error before checking a single link - on every PR, permanently, while looking like an ordinary red X. exclude_mail = true -> include_mail = false (no such key) include_fragments = true -> include_fragments = "full" (mode string) accept = [200, 429] -> accept = ["200", "429"] (strings) All three per lychee-v0.24.2's lychee.example.toml. Demonstrated in PR #29 rather than assumed, which is what issue #14 asked for. With a deliberate broken anchor: 289 links, 1 error, "Cannot find fragment", exit 2 (run 31779231033). Without it: green in 10 seconds, comfortably inside the two-minute budget (run 31779305943). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01K4KmSPBuq484Zt65qsK177
jayteemoney
force-pushed
the
ci/verify-docs-workflow
branch
2 times, most recently
from
August 14, 2026 07:24
106c924 to
a677c56
Compare
5 tasks
Contributor
Author
|
Done its job — closing without merging, as planned. Found that Runs: 31779231033 red, 31779305943 green, 31779802510 green against full main. |
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
2 participants
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.
Throwaway PR to satisfy issue #14's acceptance criterion: "Broken internal links and broken anchors both fail the build — demonstrate this in the PR."
Carries #28's workflow plus a deliberately broken anchor in
README.mdpointing atdocs/architecture.md#this-anchor-does-not-exist.Expected:
link check (internal, blocking)goes red and names that anchor. Then the anchor comes out and the same job goes green, which proves it fails for the anchor and not for something incidental.Opened from a branch in this repo rather than #28's fork so the run doesn't need approval. Closed without merging once observed.