Add Context7 compatible docs (AI-readable docs) #3703
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the 📝 WalkthroughWalkthroughAdds Context7 documentation support: new Context7 JSON config, a Stencil docs config, a script to generate markdown READMEs/INDEX/META, an npm script to run it, and integration into the publish pipeline to run and copy the generated markdown into the release docs output. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Developer/CI
participant PD as publish-docs.cjs
participant Stencil as Stencil Build
participant Gen as generate-context7-docs.cjs
participant FS as Filesystem
Dev->>PD: Run publish-docs
PD->>Stencil: Build site/docs
alt Stencil build fails
PD-->>Dev: Exit non-zero (teardown)
else Build succeeds
PD->>Gen: npm run docs:context7
alt Context7 gen fails
PD-->>Dev: Exit non-zero (teardown)
else Generation succeeds
Gen->>FS: Write www/markdown-docs (READMEs, INDEX.md, META.json)
PD->>FS: Copy www/markdown-docs -> docsDist/versions/{version}
PD-->>Dev: Success
end
end
sequenceDiagram
autonumber
actor CI as CI/DX
participant Gen as generate-context7-docs.cjs
participant Stencil as Stencil (context7 config)
participant FS as Filesystem
Note over Gen,Stencil: High-level doc generation flow
CI->>Gen: Execute
Gen->>Stencil: Build components (docs-readme)
alt Build error
Gen-->>CI: Exit with error
else Build ok
Gen->>FS: Ensure guides dir
Gen->>FS: Copy root docs (`README.md`, `CONTRIBUTING.md`)
Gen->>FS: Copy src guides (`src/contributing.md`, `src/events.md`, `src/theming.md`)
Gen->>FS: Generate `INDEX.md` (version, components table, links)
Gen->>FS: Generate `META.json` (counts, timestamp)
Gen-->>CI: Done
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
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 |
Add configuration to generate component API documentation in markdown format using Stencil's docs-readme output target. These markdown files will be published to gh-pages to make component documentation available for LLM-based tools and documentation indexers.
|
Documentation has been published to https://lundalogik.github.io/lime-elements/versions/PR-3703/ |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
publish-docs.cjs (3)
356-358: Fix commit message when pruning old patch versionsIt uses argv.remove (undefined here), producing “remove undefined”.
Apply this diff:
- if (runCommit) { - commit(`chore(docs): remove ${argv.remove}`); - } + if (runCommit) { + commit(`chore(docs): remove old patch version ${item}`); + }
122-124: Avoid exposing GH_TOKEN in command line/logsCloning with token in URL risks leakage in logs/process args. At minimum, silence exec output; ideally use a safer auth mechanism.
Apply this minimal mitigation:
function cloneDocsRepo() { if (!shell.which('git')) { shell.echo('Sorry, this script requires git'); shell.exit(1); } + const prevSilent = shell.config.silent; + shell.config.silent = true; if ( shell.exec( 'git clone --single-branch --branch gh-pages https://[email protected]/Lundalogik/lime-elements.git docsDist' ).code !== 0 ) { shell.echo('git clone failed!'); teardown(); shell.exit(1); } + shell.config.silent = prevSilent; }Longer‑term: use GitHub Actions checkout with a separate workspace/folder, or gh auth/credential helpers to avoid embedding the token in the command.
452-453: Use shelljs rm for cross‑platform cleanupshell.exec('rm -rf …') breaks on Windows; use shell.rm.
Apply this diff:
shell.exec('git checkout src/index.html stencil.config.docs.ts'); shell.echo('Removing docs repo clone in docsDist.'); - shell.exec('rm -rf docsDist'); + shell.rm('-rf', 'docsDist');
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
📒 Files selected for processing (5)
context7.json(1 hunks)generate-context7-docs.cjs(1 hunks)package.json(1 hunks)publish-docs.cjs(2 hunks)stencil.config.context7.ts(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{ts,tsx}
⚙️ CodeRabbit configuration file
**/*.{ts,tsx}: Imports from other files in the same module (lime-elements) must use relative paths. Using absolute paths for imports will cause the production build to fail.
Files:
stencil.config.context7.ts
🧠 Learnings (1)
📚 Learning: 2025-04-25T14:23:56.018Z
Learnt from: Kiarokh
PR: Lundalogik/lime-elements#3529
File: src/components/lime-ai-avatar/lime-ai-avatar.scss:1-3
Timestamp: 2025-04-25T14:23:56.018Z
Learning: In the lime-elements repository, CSS custom properties prefixed with `--lime-` are considered internal implementation details and should not be documented in JSDoc comments, while other custom properties should be documented as they are part of the public API.
Applied to files:
context7.json
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: Docs / Publish Docs
- GitHub Check: Test
- GitHub Check: Build
🔇 Additional comments (5)
package.json (1)
26-26: Add docs generator script — looks goodScript wiring is correct and consistent with the new generator.
context7.json (1)
5-11: Confirm scope of indexed docs (only latest)Config indexes versions/latest/markdown-docs only. If you intend Context7 to index all released versions, broaden the folder pattern; otherwise, this is fine.
publish-docs.cjs (2)
193-197: Run Context7 docs after build — good sequencingFail‑fast handling and teardown on error are correct.
240-248: Copying markdown docs into versioned path — goodMatches generator output path and deploy layout.
stencil.config.context7.ts (1)
10-25: Stencil Context7 docs config — LGTMOutput target, paths, and plugins look correct for docs‑readme generation.
adrianschmidt
force-pushed
the
add-context7-compatible-docs
branch
2 times, most recently
from
1bb35aa to
0f9ee67
Compare
adrianschmidt
force-pushed
the
add-context7-compatible-docs
branch
from
b36b1ac to
0282c26
Compare
Create a Node.js script that generates Context7-compatible markdown documentation by: - Running Stencil build with context7 config - Copying root documentation files (README, CONTRIBUTING) - Copying guide files (contributing, events, theming) - Generating an INDEX.md file with component catalog - Creating META.json with version and file counts Add npm script docs:context7 to run the generation process. The generated documentation will be published to gh-pages to enable LLM-based documentation indexing.
Update publish-docs.cjs to generate and publish markdown
documentation alongside Kompendium docs:
- Run npm run docs:context7 after docs:build
- Copy www/markdown-docs to docsDist/versions/{version}/
The markdown documentation will now be published to gh-pages
at /versions/{version}/markdown-docs/ for each release,
making it available for Context7 and other LLM-based
documentation indexers.
Add context7.json to configure Context7 to index documentation from the gh-pages branch at versions/latest/markdown-docs/. Configuration includes: - Branch targeting: gh-pages (where docs are published) - Folder specification: versions/latest/markdown-docs - Exclusions: build artifacts, assets, and styles - 14 usage rules covering web component patterns, installation, TypeScript support, theming, and common gotchas This enables LLM-based tools to access accurate, version-specific documentation for Lime Elements components.
adrianschmidt
force-pushed
the
add-context7-compatible-docs
branch
from
0282c26 to
51db095
Compare
adrianschmidt
changed the title
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
2 participants
Summary by CodeRabbit
New Features
Documentation
Chores
Review:
Browsers tested:
(Check any that applies, it's ok to leave boxes unchecked if testing something didn't seem relevant.)
Windows:
Linux:
macOS:
Mobile: