docs(compliance): add stable per-control anchors for external deep links - #3895
Conversation
The ATF headings carry their conformance status in the heading text
("#### I-3: Ownership Chain — ✅ FULLY MET"), so a generated anchor moves
whenever a control's status changes, and the policy rules live in table
rows with no anchor at all. Neither can be linked to durably from outside.
Add explicit `<a id="...">` anchors: control id plus name slug for the 25
ATF requirements, and the rule name itself for the 68 policy rules, since
that name is already the durable identifier. Both are independent of the
surrounding prose, so rewording a heading or changing a status no longer
moves the target.
Uses the HTML-anchor form already established in
docs/compliance/nist-ai-rmf-alignment.md rather than attr_list `{#id}`:
these docs are read on GitHub as well as the MkDocs site, and GitHub does
not support attr_list.
Refs microsoft#3811.
|
Azure Pipelines: There may be pipelines that require an authorized user to comment /azp run to run. |
PR Review Summary
Verdict: AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims. |
|
🟡 Contributor Check: MEDIUM
Automated check by AGT Contributor Check. |
|
Dipak Chaudhari (@dchaudhari7177) please read the following Contributor License Agreement(CLA). If you agree with the CLA, please reply with the following information.
Contributor License AgreementContribution License AgreementThis Contribution License Agreement (“Agreement”) is agreed to by the party signing below (“You”),
|
Refs #3811.
Adds stable per-control anchors to the two docs that carry the control taxonomy, so OpenCRE (and any other external standard) can deep link to a control and keep resolving.
Anchor scheme
docs/compliance/atf-conformance-assessment.md— 25 anchors, one per requirement,<control-id>-<name-slug>:That is the exact form the issue asked for. It matters that these are explicit rather than generated: the headings carry their conformance status inline, so the generated anchor for I-3 is
#i-3-ownership-chain--fully-mettoday and becomes#i-3-ownership-chain--partially-metthe moment the status changes. That is precisely the rot the issue calls out as worse than no anchor.docs/compliance/owasp-asi-policy-mapping.md— 68 anchors, one per policy rule. The rules live in table rows, not headings, so there is nothing to generate an anchor from at all. Each anchor is keyed on the rule name itself (#asi01-prompt-injection-override) rather than a slug of surrounding prose, because the rule name is the durable identifier — it is what the policy packs are keyed on, so it cannot be reworded without a rule rename.Why
<a id>rather than{#id}attr_listis enabled inmkdocs.yml, so{#i-3-ownership-chain}would work on the docs site. I used the HTML-anchor form because these compliance docs are also read directly on GitHub, which does not supportattr_listand would render the braces as literal text. It is also the form already established indocs/compliance/nist-ai-rmf-alignment.md.Verified
[a-z0-9][a-z0-9-]*.attr_list,md_in_html,tablesandtocextensions: 93 anchors present in the output,#i-3-ownership-chainand#asi01-prompt-injection-overrideboth resolve, and the tables still render (93 and 128 rows) — the inline anchor in the first cell does not break the row.Out of scope per the issue: the mapping content itself.