WIP: Add .docs-config.yml manifests with CI validation #2392
Conversation
When docs structure changes (new directories, renamed files, moved docs), the shakacode.com website config becomes stale because there's no enforcement linking folder structure to navigation config. This adds a .docs-config.yml manifest to both docs/ and react_on_rails_pro/docs/ that declares category ordering, file ordering, and exclusions — and a CI validator that blocks PRs if the manifest doesn't match the actual folder structure. The manifests are the source of truth that sc-website will read at build time (in a follow-up PR) instead of its current hardcoded arrays. Co-Authored-By: Claude Opus 4.6 <[email protected]>
WalkthroughIntroduce automated validation of documentation configurations via a GitHub Actions workflow and Node.js validation script. Add YAML configuration files for OSS and Pro documentation directories that specify exclusions, category ordering, and file ordering. Validation runs on relevant pull requests and pushes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
🧪 Generate unit tests (beta)
No actionable comments were generated in the recent review. 🎉 🧹 Recent nitpick comments
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 |
ihabadham
changed the title
Greptile OverviewGreptile SummaryAdds comprehensive docs configuration validation system to prevent stale navigation on shakacode.com. Creates YAML manifests that declare category ordering, file ordering, and exclusions for both OSS and Pro docs, replacing the website's current hardcoded navigation config. Key Changes:
Minor Issues:
The implementation is solid and addresses a real pain point of broken sidebar ordering sitting undetected in production. Confidence Score: 5/5
Important Files Changed
Sequence DiagramsequenceDiagram
participant Dev as Developer
participant GH as GitHub PR
participant CI as CI Workflow
participant Val as Validator Script
participant FS as File System
Dev->>GH: Push changes to docs/
GH->>CI: Trigger validate-docs-config.yml
CI->>CI: Setup Node.js 20
CI->>CI: Install js-yaml & micromatch to /tmp
CI->>Val: Run validator for docs/
Val->>FS: Read .docs-config.yml
Val->>FS: Scan directory structure
Val->>Val: Validate schema
Val->>Val: Check category completeness
Val->>Val: Check file existence
Val->>Val: Check stale entries
Val-->>CI: Return errors/warnings
CI->>Val: Run validator for react_on_rails_pro/docs/
Val->>FS: Read .docs-config.yml
Val->>FS: Scan directory structure
Val->>Val: Perform all validations
Val-->>CI: Return errors/warnings
CI-->>GH: Report success/failure
GH-->>Dev: Block merge if errors found
|
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| # Sidebar category order. Uses folder names (kebab-case). | ||
| # "" = root-level files (no category header). | ||
| categoryOrder: | ||
| - '' |
There was a problem hiding this comment.
Inconsistent quote style - OSS config uses "" for empty string (line 22 in docs/.docs-config.yml), but this uses ''
| - '' | |
| - "" |
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
The validate-docs-config.cjs script requires these packages but they were only available as transitive dependencies. Knip flagged them as unlisted dependencies, causing CI to fail. Co-Authored-By: Claude Opus 4.6 <[email protected]>
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| runs-on: ubuntu-latest | ||
| env: | ||
| NODE_PATH: /tmp/docs-validator/node_modules | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
|
|
||
| - uses: actions/setup-node@v4 | ||
| with: | ||
| node-version: '20' | ||
|
|
||
| - name: Install validator dependencies | ||
| run: npm install --prefix /tmp/docs-validator --no-package-lock js-yaml micromatch | ||
|
|
||
| - name: Validate OSS docs config | ||
| run: node scripts/validate-docs-config.cjs docs | ||
|
|
||
| - name: Validate Pro docs config | ||
| run: node scripts/validate-docs-config.cjs react_on_rails_pro/docs |
Check warning
Code scanning / CodeQL
Workflow does not contain permissions Medium
Show autofix suggestion
Hide autofix suggestion
Copilot Autofix
AI 2 days ago
In general, the fix is to add an explicit permissions block that grants only the minimal scopes required. For this workflow, the steps only read repository contents and run local Node scripts, so contents: read is sufficient. We can attach the permissions block either at the root of the workflow (applying to all jobs) or directly under the validate job. To keep the change tightly scoped to the highlighted job, we’ll add it under jobs.validate.
Concretely, in .github/workflows/validate-docs-config.yml, add a permissions: section under jobs: validate: at the same indentation level as runs-on. The block should be:
permissions:
contents: readNo new imports or external tools are needed; this is pure workflow configuration. Existing functionality is unaffected because the workflow never wrote to the repository or other GitHub resources.
| @@ -18,6 +18,8 @@ | ||
| jobs: | ||
| validate: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| contents: read | ||
| env: | ||
| NODE_PATH: /tmp/docs-validator/node_modules | ||
| steps: |
size-limit report 📦
|
2 participants
Summary
.docs-config.ymlmanifest files todocs/(OSS) andreact_on_rails_pro/docs/(Pro) that declare category ordering, file ordering, and exclusions for the shakacode.com docs websitescripts/validate-docs-config.cjs) that runs on every PR touching docs and blocks merge if the manifest doesn't match the actual folder structure.github/workflows/validate-docs-config.yml) that triggers validation on PRs and pushes to masterWhy
When docs structure changes (new directories, renamed/moved files), the shakacode.com website's hardcoded navigation config becomes stale — broken sidebar ordering has sat in production for weeks/months with no detection. This makes the manifests the single source of truth that sc-website will read at build time (in a follow-up PR), replacing its current hardcoded arrays.
What the validator checks
categoryOrder(ERROR if missing)fileOrdermust exist on disk (ERROR if missing).mdfiles require""incategoryOrder(ERROR if missing)categoryOrderorfileOrderarrays (ERROR)Notes
react-server-componentsandrelease-notesincategoryOrder. These folders already exist and appear dynamically at the end of the sidebar today — the manifest just makes the implicit order explicit..cjsextension because the repo has"type": "module"inpackage.json.js-yamlandmicromatchto a temp directory (/tmp/docs-validator) to avoid touching the repo'spnpm-lock.yaml.Test plan
node scripts/validate-docs-config.cjs docspassesnode scripts/validate-docs-config.cjs react_on_rails_pro/docspassescategoryOrder→ validator should ERRORfileOrder→ validator should ERROR🤖 Generated with Claude Code
Summary by CodeRabbit