Surface deprecated prebuilt detection rules as a sibling nav page#3167
Surface deprecated prebuilt detection rules as a sibling nav page#3167
Conversation
- Auto-detects _deprecated/ subfolders in detection rule folders and generates
a sibling "Deprecated prebuilt detection rules" page in the nav
- Optional deprecated_file: field in docset.yml names a .md file whose content
prefixes the auto-generated deprecated rules listing
- Each deprecated rule page shows a deprecation warning with the deprecation date
- Fixed stateful TomlParser causing serve-mode parse failures on repeated builds
- Fixed serve --path scope: in-memory write FS now scoped to git root of --path
so output at {externalRepo}/.artifacts is within allowed write scope
- Fixed serve sourcePath: ReloadGeneratorService now passes DocumentationCheckoutDirectory
(git root) rather than DocumentationSourceDirectory (docs/ subfolder)
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
When a page is a hidden nav leaf (e.g. individual detection rule pages),
the JavaScript active-state logic couldn't find a matching nav link and
left the sidebar with nothing selected.
Fix: emit <meta name="docs:nav-active" content="{parentUrl}"> in the
page <head> when current.Hidden is true, pointing to the nearest visible
ancestor. pages-nav.ts reads this tag and uses that URL to mark the
correct nav item as current instead of window.location.pathname.
This works for both deprecated rules (/deprecated-detection-rules parent)
and active prebuilt rules (/ parent = detection rules overview at index.md).
Visible pages are unaffected (no meta tag emitted).
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 48 minutes and 18 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Enterprise Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThis pull request introduces support for deprecated detection rules in the documentation system. It adds an in-memory file system factory scoped to git roots, extends the TOC resolution to detect and generate deprecated rule overviews as sibling references, updates YAML parsing to recognize deprecated rules, and adds detection rule maturity and deprecation date metadata. The build process creates synthetic overview markdowns for deprecated rules, and the frontend uses a Sequence DiagramsequenceDiagram
participant Build as Build System
participant TOC as TOC Resolution
participant FS as File System
participant HTML as HTML Renderer
participant Client as Browser Client
participant Nav as Navigation
Build->>TOC: Process detection rule overview reference
TOC->>FS: Check for _deprecated subfolder
alt Deprecated folder exists
FS-->>TOC: Folder found
TOC->>TOC: Create DeprecatedSiblingRef
TOC->>Build: Append deprecated overview reference
Build->>FS: Generate DeprecatedDetectionRuleOverviewFile
FS-->>Build: Overview markdown created
end
Build->>HTML: Render page with detection rule
alt Rule is deprecated
HTML->>HTML: Insert deprecation warning block
end
HTML->>HTML: Compute NavigationActiveUrl<br/>(closest visible ancestor)
HTML->>Client: Emit docs:nav-active meta tag
Client->>Nav: Read meta tag content
Nav->>Nav: Query for matching href
Nav->>Nav: Apply current class to ancestor link
Suggested labels
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
src/Elastic.Documentation.Configuration/Toc/TableOfContentsYamlConverters.cs (1)
75-87:⚠️ Potential issue | 🟡 MinorRemove unused
deprecated_detection_rulesfrom parsing logic.The
deprecated_detection_ruleskey is parsed into the dictionary but never read anywhere in the codebase. The PR auto-discovers deprecated rules via folder scanning, making this key dead code. Remove it from the condition or document why it's retained.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/Elastic.Documentation.Configuration/Toc/TableOfContentsYamlConverters.cs` around lines 75 - 87, In the YAML parsing branch inside TableOfContentsYamlConverters (the else-if that checks key.Value against "detection_rules" or "exclude" or "deprecated_detection_rules"), remove "deprecated_detection_rules" from that condition and any related parsing branch so the parser no longer adds that key into the dictionary; if you intentionally want to keep it, add a comment explaining why and where it's consumed. Update or remove any tests or usages that expect deprecated_detection_rules to be present and ensure the parsing of the remaining keys ("detection_rules", "exclude") is unchanged.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In
`@src/Elastic.Documentation.Configuration/Toc/TableOfContentsYamlConverters.cs`:
- Around line 75-87: In the YAML parsing branch inside
TableOfContentsYamlConverters (the else-if that checks key.Value against
"detection_rules" or "exclude" or "deprecated_detection_rules"), remove
"deprecated_detection_rules" from that condition and any related parsing branch
so the parser no longer adds that key into the dictionary; if you intentionally
want to keep it, add a comment explaining why and where it's consumed. Update or
remove any tests or usages that expect deprecated_detection_rules to be present
and ensure the parsing of the remaining keys ("detection_rules", "exclude") is
unchanged.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Enterprise
Run ID: 81e46472-e23f-4459-8cba-6b14b17737ff
📒 Files selected for processing (15)
src/Elastic.Documentation.Configuration/FileSystemFactory.cssrc/Elastic.Documentation.Configuration/Toc/DetectionRules/DetectionRuleOverviewRef.cssrc/Elastic.Documentation.Configuration/Toc/DocumentationSetFile.cssrc/Elastic.Documentation.Configuration/Toc/TableOfContentsYamlConverters.cssrc/Elastic.Documentation.Site/Assets/pages-nav.tssrc/Elastic.Documentation.Site/Layout/_Head.cshtmlsrc/Elastic.Documentation.Site/_ViewModels.cssrc/Elastic.Markdown/Extensions/DetectionRules/DetectionRule.cssrc/Elastic.Markdown/Extensions/DetectionRules/DetectionRuleFile.cssrc/Elastic.Markdown/Extensions/DetectionRules/DetectionRulesDocsBuilderExtension.cssrc/Elastic.Markdown/HtmlWriter.cssrc/Elastic.Markdown/Page/Index.cshtmlsrc/Elastic.Markdown/Page/IndexViewModel.cssrc/tooling/docs-builder/Http/InMemoryBuildState.cssrc/tooling/docs-builder/Http/ReloadGeneratorService.cs
GHSA-g94r-2vxg-569j OpenTelemetry.Api 1.13.1 GHSA-mr8r-92fq-pj8p OpenTelemetry.Exporter.OpenTelemetryProtocol 1.13.1 GHSA-q834-8qmm-v933 OpenTelemetry.Exporter.OpenTelemetryProtocol 1.13.1 Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
2 participants
Why
Elastic's prebuilt detection rules repo contains a
_deprecated/folder of rules that have been retired. These rules were previously invisible to users browsing the docs — there was no way to discover them, understand why they exist, or know what replaced them. Users navigating directly to a deprecated rule page (e.g. from a bookmark or external link) also lost their nav context entirely: nothing in the sidebar was highlighted.What
Deprecated rules page
When the
detection-rulesplugin processes a rule folder that contains a_deprecated/subfolder, it automatically generates a sibling "Deprecated prebuilt detection rules" page in the navigation alongside the active rules overview. No docset.yml changes are required for the page to appear.The page lists all deprecated rules alphabetically by domain, linking to individual rule pages. Each individual rule page shows a deprecation warning admonition with the date the rule was deprecated.
Optional preface
The security team can supply introductory content for the deprecated rules page by adding a markdown file to the detection-rules docs folder and referencing it in
docset.yml:When
deprecated_fileis set, the content of that file prefixes the auto-generated rules listing. This lets the team explain what deprecated rules are, what users should do with them, and link to related guidance — all without touching the docs-builder codebase.Follow-up: elastic/detection-rules#5968 adds this preface file (draft, cannot merge until this PR is released to production).
Nav active state for hidden pages
Individual rule pages (both active and deprecated) are hidden nav leaves — they exist in the nav tree for ordering/breadcrumb purposes but don't appear as visible links in the sidebar. Before this change, landing on a rule page left the sidebar with nothing selected.
The fix emits a
<meta name="docs:nav-active" content="{parentUrl}">tag server-side when the current page is a hidden nav item. The client reads this and highlights the nearest visible ancestor instead. This restores nav context for rule pages and fixes the same issue on the live site for any hidden page.Verification
Run locally against the detection-rules repo:
http://localhost:3000/deprecated-detection-rules— lists deprecated ruleshttp://localhost:3000/rules/_deprecated/<rule>— deprecation warning, sidebar highlights deprecated rules pagehttp://localhost:3000/rules/<category>/<rule>— sidebar highlights prebuilt rules overview