📖 [Docs]: Process-PSModule reference uses its canonical site - #158
Merged
Conversation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
marked this pull request as ready for review
August 9, 2026 09:15
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Aug 9, 2026
markdownlint's MD051 recognises a custom heading anchor only when the braces contain no surrounding whitespace. With the spaced form the heading keeps its slugified anchor, so same-page references such as [FR1](#fr1) -- the form Spec-Driven-Development.md tells authors to use -- are reported as broken link fragments, and a spec written by following that page fails the linter the ecosystem runs in CI. Convert all 20 occurrences: 6 in Spec-Driven-Development.md, covering the prose that introduces the form and the specification template, and 14 in deployment/spec.md. Both forms render identically under Python-Markdown's attr_list, which this site enables, so the published output is unchanged. Test-DocumentationLink.ps1 matches the id with \s* around the brace contents, so it resolves either form. The 11 anchors this commit originally converted in process-psmodule/spec.md are gone: #158 retired that capability's pages in favour of its canonical site, and the file no longer exists. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This was referenced Aug 9, 2026
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Aug 9, 2026
markdownlint's MD051 recognises a custom heading anchor only when the braces contain no surrounding whitespace. With the spaced form the heading keeps its slugified anchor, so same-page references such as [FR1](#fr1) -- the form Spec-Driven-Development.md tells authors to use -- are reported as broken link fragments, and a spec written by following that page fails the linter the ecosystem runs in CI. Convert 16 occurrences: 2 in the Spec-Driven-Development.md prose that introduces the form, and 14 in deployment/spec.md. Both forms render identically under Python-Markdown's attr_list, which this site enables, so the published output is unchanged. Test-DocumentationLink.ps1 matches the id with \s* around the brace contents, so it resolves either form. Two pages this commit used to touch have moved on: #158 retired process-psmodule/spec.md with the rest of that capability's pages, and #160 moved the specification templates out to Spec-Driven-Development-Templates.md. The anchors that arrived with #160, there and in its new worked example, are converted in the commit that follows this one. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Aug 9, 2026
…own linter (#144) Requirement anchors in specifications now use the one form that both the documentation site and the Markdown linter understand, so a specification written by copying the template out of [Spec-Driven Development Templates](https://msxorg.github.io/docs/Ways-of-Working/Spec-Driven-Development-Templates/) lints clean with no hand-editing afterwards — in this repository and in any repository that inherits the standard without inheriting this one's linter configuration. ## Fixed: References to requirements no longer report as broken links The Requirements section tells authors to give each requirement an explicit anchor and to reference it as `[FR1](#fr1)`. Written with spaces inside the braces, that anchor is invisible to [markdownlint](https://github.com/DavidAnson/markdownlint) rule [MD051](https://github.com/DavidAnson/markdownlint/blob/main/doc/md051.md): the heading keeps its slugified anchor instead, and same-page references to the identifier resolve to nothing. Following the page therefore produced a document that failed the linter the ecosystem runs in CI. Anchors are now written without the inner spaces: ```markdown ### FR1 — <what the capability does, behavioral, testable, no technology> {#fr1} ``` Nothing else about the form changes. The anchor is still the identifier alone, still append-only, and still referenced as `[FR1](#fr1)` on the same page and `[FR1](spec.md#fr1)` across pages. Both brace forms render identically under [Python-Markdown's `attr_list`](https://python-markdown.github.io/extensions/attr_list/), which this site enables, so the published pages are byte-for-byte the same as before. The specification that still used the spaced form has been converted, along with every skeleton in the templates page, so what an author copies matches the rule the standard now enforces. ## Changed: A reference to a heading that does not exist now fails the build MD051 was switched off in this repository precisely because it could not read the spaced anchors, with a script covering the gap instead. With the anchors converted, the rule is on again and a link to a heading that does not exist fails the lint job like any other error. Contributors get that caught in CI rather than discovering it as a dead link on the published site. ## Changed: The Markdown standard now documents the anchor form and the rule that enforces it The anchor syntax previously appeared only in Spec-Driven Development, framed as a convention for specifications — which is how the broken form came to be copied into pages and repositories that had nothing to do with specifications. It is now written down in the [Markdown standard](https://msxorg.github.io/docs/Coding-Standards/Markdown/) as a rule for any heading on any page, together with the limitation worth knowing: the linter checks same-file fragments only, so a clean lint run does not prove that a cross-file `spec.md#fr1` link resolves. Custom heading anchors are not defined by original Markdown, CommonMark, or GFM; this site gets `{#id}` from its enabled Python-Markdown `attr_list` extension, so the braces render literally in GitHub's file view but become the heading ID on the published site. --- <details> <summary>Technical details</summary> Six commits, each independently reviewable: 1. **`31d41cd` — the anchors.** Mechanical conversion of `{ #id }` to `{#id}`, 16 occurrences over 2 files — the Spec-Driven-Development prose that introduces the form (2, on one line) and `deployment/spec.md` (14, FR1–FR10 and NFR1–NFR4). No rewording, no restructuring, no reflowing. 2. **`7b21fee` — the linter disable that the spaced form caused.** `MD051: false` removed from `.github/linters/.markdown-lint.yml`. Gated, not assumed: the line was removed first and `markdownlint-cli2` v0.23.2 (markdownlint v0.41.1) run with that real configuration over every tracked Markdown file, reporting `0 issues`. Clean, so the removal stands. Had it surfaced unrelated findings, the disable would have been restored with a corrected comment and the findings tracked separately rather than fixed in passing. 3. **`a2c9a0d` — the checker's own help.** The three `{ #id }` examples in the comment-based help and parsing comment of `.github/scripts/Test-DocumentationLink.ps1` now show `{#id}`. Examples only; the matching expression is untouched. The colon-prefixed `{: #id ... }` in the same comment is left as it was — the expression genuinely tolerates that variant, so converting it would have made the help wrong. 4. **`f5fa802` — the standard that should have carried the rule.** `src/docs/Coding-Standards/Markdown.md` states that the shared configuration is the source of truth and then enumerates the rules in two tables; MD051 was in neither. It had been disabled in the config and never recorded, so the page was already out of step before this branch. Commit 2 made that omission live — the rule now fails the build for every page, not just specifications — so the page gains an MD051 row in **Enforced rules**, the anchor syntax as one bullet in **Style beyond the linter**, and the same-file limitation stated once. Verified MD051 is not present in **Relaxed on purpose**; it was not, so nothing was removed. 5. **`1a7c25c` — the anchors that arrived while this branch waited.** [#160](#160) moved the skeletons out to `Spec-Driven-Development-Templates.md` and added a worked requirement example, both written in the spaced form — which was still what the standard taught, and which nothing would have caught while MD051 was disabled. Six anchors converted: 5 in the new templates page, 1 in the new example. All six sit inside fenced code blocks, so neither markdownlint nor `Test-DocumentationLink.ps1` examines them and no check was failing; they matter because a skeleton is the text an author copies, and that is the vector that carried the broken form into PSModule/Markdown#33. 6. **`9a66332` — whose syntax this actually is.** The page opens by saying documentation is authored in GitHub Flavored Markdown, and commit 4 then made `{#id}` an enforced rule — but GFM defines no attribute syntax, and neither does CommonMark nor Gruber's original. The construct belongs to individual flavors: PHP Markdown Extra and Python-Markdown, kramdown's inline attribute lists, Pandoc. This site gets it from `attr_list`. Verified against the renderers rather than their documentation — GitHub's `POST /markdown` with `mode=gfm` returns `<h3>FR1 {#fr1}</h3>`, and the same literal output for `{ #fr1 }` and `{: #fr1 }`, while Python-Markdown 3.10.2 with `attr_list` turns all three into `<h3 id="fr1">`. The rule now says so where it is stated, so an author who sees braces in a repository file view knows that is expected rather than a mistake, and knows `{#id}` wins as an intersection of implementations rather than by any specification. **Rebased twice while waiting for review**, each time onto current `main` with no content from the incoming work reverted: - [#158](#158) retired the `process-psmodule` pages in favour of that capability's canonical site, deleting a file this branch had edited. A modify/delete conflict, resolved by keeping the deletion — the 11 anchors converted there went with the page. - [#160](#160) rewrote Spec-Driven-Development and replaced its inline templates with a link to the new templates page. A content conflict, resolved by taking `main`'s prose in full; the template conversions this branch used to carry now apply to the new page instead, in commit 5. **How much MD051 was actually catching.** MD051 validates *same-file* fragments only, and skips fenced code blocks entirely. Across the spaced anchors on this branch, exactly 2 references were being reported — `[FR8](#fr8)` and `[FR9](#fr9)`, both in `deployment/spec.md`. Cross-file references of the `spec.md#fr1` form were never checked by MD051 at all and depend on `Test-DocumentationLink.ps1`, which is why that script remains the broader of the two checks and stays in CI. This is the measurement that makes removing the disable safe: there were only ever two findings to clear, and they are cleared. The reach of the defect was in what the templates *taught* downstream repositories, not in the volume of errors produced here. **Why `{#id}` and not `{: #id }`.** `attr_list` accepts `{#fr1}`, `{ #fr1 }` and `{: #fr1 }`; markdownlint understands only the unspaced one, so it is the single form that satisfies the renderer and CI at once. `Test-DocumentationLink.ps1` matches with `\{\s*:?\s*#([-\w]+)[^}]*\}\s*$`, where `\s*` permits zero spaces, so the converted anchors resolve under the existing checker with no change to it. **Verification** after the second rebase, using only tooling the repository already provides: - `Test-DocumentationLink.ps1` — `All documentation links resolve (119 file(s) scanned)`, exit 0. - `Update-DocumentationIndex.ps1 -Check` — exit 0, no diff. - `markdownlint-cli2` with `.github/linters/.markdown-lint.yml`, MD051 now enabled, across all 128 tracked Markdown files — `0 issues`. - `Invoke-PesterSuite.ps1` — 54 passed, 0 failed, across 4 suites. **Implementation plan progress** — all five steps of #141 are delivered here: the documentation conversions, the linter-configuration removal with its gate, and the comment-based help examples. The plan's `process-psmodule/spec.md` step is satisfied by that file's removal in #158. Commits 4 and 5 are beyond the issue's plan and close drift the plan itself would otherwise have left behind. Nothing is deferred to a follow-up. **Issue convergence sweep** — scope was every open issue in `MSXOrg/docs`. #143 (naming the downstream artifacts a standard governs, so changing it has a known blast radius) is the closest match, and commit 4 is an instance of exactly that concern rather than a resolution of it — the general mechanism it asks for is not delivered here, so it takes no closing keyword. #142 (cross-repository links the Markdown standard tells authors to write) and #105 (co-locating Gherkin acceptance tests with the FR/NFR they verify) concern different surfaces. No additional issue is fully satisfied. | Changed surface | Standards checked | Framework docs checked | Result | | --- | --- | --- | --- | | `src/docs/**` (Markdown) | Markdown | Documentation Model, Spec-Driven Development | Aligned | | `.github/linters/**` (linter configuration) | Markdown | Repository Standard | Fixed in this PR — the configuration and the standard documenting it now agree | | `.github/scripts/**` (PowerShell) | PowerShell — Scripts, Documentation | Repository Standard | Aligned | </details> <details> <summary>Relevant issues (or links)</summary> - Resolves #141 ### Related work - References #143 - References #158 - References #160 - References PSModule/Markdown#33 </details> --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
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
1 participant
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.
Process-PSModule guidance will use the canonical PSModule documentation site, giving readers one authoritative reference once that site is publicly available.
Changed: Process-PSModule documentation reference
The MSX documentation navigation no longer publishes a separate local Process-PSModule reference. Every remaining documentation reference points to the canonical Process-PSModule documentation URL.
Technical details
src/docs/Capabilities/process-psmodule/, including its media assets, and removes its Zensical navigation block.PSModule/Process-PSModule#447merges, its target Pages deployment serveshttps://psmodule.io/docs/Modules/Process-PSModule/, and the canonical links have been verified.Relevant issues (or links)