docs(repo): fix critical and major documentation issues#46
Merged
zrosenbauer merged 23 commits intomainfrom Mar 21, 2026
Merged
docs(repo): fix critical and major documentation issues#46zrosenbauer merged 23 commits intomainfrom
zrosenbauer merged 23 commits intomainfrom
Conversation
Address findings from a comprehensive 5-agent documentation review covering references, concepts, getting started, and icon docs. Key fixes: - Correct Section/Workspace type names and field structures - Document missing CLI commands (check, draft) and build --check flag - Add undocumented top-level config fields (theme, actions, seo, sidebar) - Fix auto-discovery examples (remove invalid discovery wrapper) - Correct default sort behavior documentation - Fix broken cross-reference links (/reference/ → /references/) - Update quick-start config examples and command table - Fix icon docs formatting and terminology Co-Authored-By: Claude <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: d0979a4 The changes in this PR will be included in the next version bump. This PR includes changesets to release 4 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughLarge documentation and configuration refactor: new DOCS-REVIEW report, config schema changes (Entry→Section, titleFrom→title {from,transform}, path→prefix), new CLI commands ( Changes
Sequence Diagram(s)sequenceDiagram
rect rgba(200,230,201,0.5)
participant Dev as Developer
end
rect rgba(187,222,251,0.5)
participant CLI as zpress CLI
participant Validator as Validator
participant LinkChecker as Link Checker
end
rect rgba(255,224,178,0.5)
participant CI as CI/CD
end
Dev->>CLI: run `zpress check` (or CI triggers)
CLI->>Validator: validate config/schema (TitleConfig, Section, prefix)
Validator-->>CLI: validation results
CLI->>LinkChecker: crawl docs for broken/stale links
LinkChecker-->>CLI: link report
CLI->>Dev: exit code + report (fail on critical issues)
CLI->>CI: expose failure/success status
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
Routes use /reference/ (singular) for configuration, cli, and frontmatter but /references/ (plural) for icons. Align all doc links to match the actual zpress.config.ts link mappings. Co-Authored-By: Claude <noreply@anthropic.com>
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
DOCS-REVIEW.md (1)
240-251: Link Audit table may be stale after this PR's fixes.Several links listed as "Likely broken" in the audit table are being fixed in this same PR:
- Line 244:
/reference/configuration→ fixed in quick-start.md (per PR objectives)- Line 246:
/reference/cli→ fixed in templates.md (line 256 in this PR)Consider updating this audit report to reflect the fixes applied in this PR, or add a note indicating which issues have been addressed.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@DOCS-REVIEW.md` around lines 240 - 251, Update the Link Audit table in DOCS-REVIEW.md to reflect that the two "Likely broken" links have been fixed in this PR: change the status for `/reference/configuration` (quick-start.md entry) and `/reference/cli` (templates.md entry) from "Likely broken" to "Fixed" or "Resolved" and add a brief parenthetical note referencing the fixes made in quick-start.md and templates.md respectively so the audit no longer appears stale.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@DOCS-REVIEW.md`:
- Line 245: Remove the false-positive audit entry that flags `/references/icons`
as broken: locate the audit row that contains the text "`/references/icons` |
workspaces.md:64" in DOCS-REVIEW.md and delete that entry so the audit no longer
reports this valid path; ensure no other rows referring to `/references/icons`
remain and save the updated file.
---
Nitpick comments:
In `@DOCS-REVIEW.md`:
- Around line 240-251: Update the Link Audit table in DOCS-REVIEW.md to reflect
that the two "Likely broken" links have been fixed in this PR: change the status
for `/reference/configuration` (quick-start.md entry) and `/reference/cli`
(templates.md entry) from "Likely broken" to "Fixed" or "Resolved" and add a
brief parenthetical note referencing the fixes made in quick-start.md and
templates.md respectively so the audit no longer appears stale.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d19cfae6-9f00-42d0-b78a-9928188430eb
📒 Files selected for processing (23)
DOCS-REVIEW.mddocs/concepts/auto-discovery.mddocs/concepts/deployment.mddocs/concepts/dynamic-content.mddocs/concepts/frontmatter.mddocs/concepts/landing-pages.mddocs/concepts/navigation.mddocs/concepts/sections-and-pages.mddocs/concepts/themes.mdxdocs/concepts/workspaces.mddocs/documentation-framework/templates.mddocs/getting-started/quick-start.mddocs/references/cli.mddocs/references/configuration.mddocs/references/icons/colors.mdxdocs/references/icons/overview.mdxdocs/references/icons/technology/databases.mdxdocs/references/icons/technology/frameworks.mdxdocs/references/icons/technology/infrastructure.mdxdocs/references/icons/technology/integrations.mdxdocs/references/icons/technology/languages.mdxdocs/references/icons/technology/overview.mdxdocs/references/icons/technology/tooling.mdx
…ntent
- Replace all deprecated titleFrom/titleTransform with title: { from: '...' }
syntax across auto-discovery, recommended, and scaling docs
- Fix Feature card icon example in colors.mdx — Feature accepts string
only, not { id, color } objects
- Add landing page mode documentation explaining auto/cards/overview/false
- Rewrite title derivation section to teach modern TitleConfig syntax first
Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
docs/concepts/auto-discovery.md (1)
49-52: Refine transform example to preserve readable titles.The example currently ignores
titleand returns a slug-derived string, which can produce non-display-friendly output. Prefer combining numeric slug prefix with the derivedtitle.Suggested example tweak
title: { from: 'auto', - transform: (title, slug) => slug.replace(/^(\d+)-/, '$1. '), + transform: (title, slug) => { + const m = slug.match(/^(\d+)-/) + return m ? `${m[1]}. ${title}` : title + }, },🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/concepts/auto-discovery.md` around lines 49 - 52, The transform function for the title currently ignores the incoming title and returns a slug-derived string; update the transform used in the title config (the title.transform function) to preserve the human-readable title while still extracting and prepending the numeric prefix from slug: parse the numeric prefix from slug (using the same regex /^(\d+)-/), and if a prefix exists return `${prefix}. ${title}` (falling back to title or the slug-derived value if title is empty) so the display title preserves readability while keeping the numeric ordering.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/concepts/sections-and-pages.md`:
- Around line 159-164: The table of section fields documents `icon` but omits
the `iconColor` field; update the fields table to include a new row for
`iconColor` (Type: string | ColorConfig or the project's canonical type) with a
concise Description explaining it controls the color of section icons, and
ensure it aligns with the existing column formatting and ordering alongside
`icon` and `card` so the section fields docs are complete.
In `@docs/documentation-framework/recommended.md`:
- Line 42: There are duplicate title keys in the same object (a static title
like title: 'Guides' and a derived title like title: { from: 'heading' }) which
causes the latter to overwrite the former; pick one representation per object
and remove the other: either keep the static label (remove title: { from:
'heading' }) or convert the static label to the derived form (replace title:
'Guides' with title: { from: 'heading' }), and apply the same change to the
other duplicated title occurrences referenced (the other objects that contain
both title: '...' and title: { from: 'heading' }). Ensure each section object
has a single title field.
In `@docs/documentation-framework/scaling.md`:
- Line 30: Replace the duplicate TypeScript object key usage where examples
define both a literal title (e.g., title: 'SectionName') and a derivation entry
title: { from: 'heading' } by renaming the derivation property to a
non-conflicting name (suggestion: pageTitle or discoveryTitle); update all
occurrences of the derivation form "title: { from: 'heading' }" in the examples
to "pageTitle: { from: 'heading' }" (or your chosen name) so the explicit title
string remains the sole title key, and leave the separate example that
intentionally uses title: { from: 'heading' } unchanged.
In `@docs/getting-started/quick-start.md`:
- Around line 26-29: The config example's from field ('from:
"docs/getting-started/*.md"') conflicts with the Project structure snippet which
references 'docs/intro.md'; update one so both match: either change the from
value to 'docs/*.md' or 'docs/intro.md' to match the snippet, or update the
Project structure snippet to list the getting-started folder and files (e.g.,
docs/getting-started/*.md); ensure consistency between the 'from' value and the
Project structure example.
---
Nitpick comments:
In `@docs/concepts/auto-discovery.md`:
- Around line 49-52: The transform function for the title currently ignores the
incoming title and returns a slug-derived string; update the transform used in
the title config (the title.transform function) to preserve the human-readable
title while still extracting and prepending the numeric prefix from slug: parse
the numeric prefix from slug (using the same regex /^(\d+)-/), and if a prefix
exists return `${prefix}. ${title}` (falling back to title or the slug-derived
value if title is empty) so the display title preserves readability while
keeping the numeric ordering.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e35f261d-fa43-4e1e-90c5-77bd0dab706a
📒 Files selected for processing (10)
docs/concepts/auto-discovery.mddocs/concepts/dynamic-content.mddocs/concepts/landing-pages.mddocs/concepts/sections-and-pages.mddocs/concepts/themes.mdxdocs/concepts/workspaces.mddocs/documentation-framework/recommended.mddocs/documentation-framework/scaling.mddocs/getting-started/quick-start.mddocs/references/icons/colors.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/concepts/landing-pages.md
- docs/concepts/themes.mdx
- docs/concepts/workspaces.md
- docs/concepts/dynamic-content.md
- Add vercel.json with build/output/install/ignore configuration - Add docs:dev script to root package.json - Remove CNAME file and GitHub Pages workflow - Add .vercel to .gitignore Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
.gitignore (1)
14-16: Minor redundancy:.vercelentry duplicates.vercel/coverage.Line 15 (
.vercel/) ignores directories, while line 53 (.vercel) ignores both files and directories with that name. Since the Vercel CLI only creates a.verceldirectory, line 53 makes line 15 redundant. Consider keeping only one entry for clarity.Also applies to: 53-53
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.gitignore around lines 14 - 16, The .gitignore currently contains both ".vercel/" and ".vercel" entries which are redundant; remove one to keep a single canonical ignore rule (prefer the simpler ".vercel" which covers both files and directories) by deleting the duplicate ".vercel/" or ".vercel" line so only one entry remains.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@vercel.json`:
- Line 6: Update the "ignoreCommand" value in vercel.json to use git pathspec
glob syntax so the packages/*/README.md pattern is recognized; specifically
replace the current git diff invocation in the "ignoreCommand" key with one that
uses '--quiet' and the '--' separator and prefixes the packages pattern with
':(glob)' (e.g., use git diff --quiet HEAD^ HEAD -- vercel.json zpress.config.ts
docs/ contributing/ ':(glob)packages/*/README.md') so Git performs glob
expansion correctly.
---
Nitpick comments:
In @.gitignore:
- Around line 14-16: The .gitignore currently contains both ".vercel/" and
".vercel" entries which are redundant; remove one to keep a single canonical
ignore rule (prefer the simpler ".vercel" which covers both files and
directories) by deleting the duplicate ".vercel/" or ".vercel" line so only one
entry remains.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 4b33b8ca-8c0e-491d-b6b1-71791b3f4584
📒 Files selected for processing (5)
.github/workflows/docs.yml.gitignoreCNAMEpackage.jsonvercel.json
💤 Files with no reviewable changes (2)
- CNAME
- .github/workflows/docs.yml
- Add explicit features array to config with real descriptions instead of auto-generated cards with placeholder text - Swap hero actions: lead with "Get Started" (brand), "Learn More" (alt) - Tighten introduction copy — punchier, less verbose - Add one-liner CLI example to introduction - Sync feature card descriptions between config and introduction page - Use correct icon color names (amber, cyan instead of orange, teal) Co-Authored-By: Claude <noreply@anthropic.com>
Better captures the value prop — it's not about having no config, it's about not needing to do the work other tools require (plugins, theme wiring, file restructuring). zpress has perfect defaults that match the 80% use case. Co-Authored-By: Claude <noreply@anthropic.com>
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)
zpress.config.ts (1)
142-157:⚠️ Potential issue | 🟡 MinorNormalize URL paths to use
/references/(plural) consistentlyLines 145, 150, and 155 use
/reference/while the Icons subsection and source file paths use/references/. Update these three links to match.Suggested fix
items: [ { title: 'Configuration', - link: '/reference/configuration', + link: '/references/configuration', from: 'docs/references/configuration.md', }, { title: 'CLI Commands', - link: '/reference/cli', + link: '/references/cli', from: 'docs/references/cli.md', }, { title: 'Frontmatter Fields', - link: '/reference/frontmatter', + link: '/references/frontmatter', from: 'docs/references/frontmatter.md', },🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@zpress.config.ts` around lines 142 - 157, Update the three menu item link values that currently use the singular path to the plural form: change the link for the item with title 'Configuration' from '/reference/configuration' to '/references/configuration', change the link for 'CLI Commands' from '/reference/cli' to '/references/cli', and change the link for 'Frontmatter Fields' from '/reference/frontmatter' to '/references/frontmatter' so they match the existing '/references/' paths used elsewhere.
🧹 Nitpick comments (1)
docs/getting-started/introduction.mdx (1)
28-28: Use “Markdown” capitalization for consistency.Consider capitalizing
markdown→Markdownin this sentence to match common technical style.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/getting-started/introduction.mdx` at line 28, Summary: The word "markdown" should use title-style capitalization for consistency. Fix: locate the sentence containing "Tell your AI to write markdown, run `zpress dev`, done." (the paragraph starting "**Built for the vibe.**") and change "markdown" to "Markdown"; scan the same document for other instances of "markdown" and apply consistent capitalization where used as the technology name.
🤖 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 `@zpress.config.ts`:
- Around line 142-157: Update the three menu item link values that currently use
the singular path to the plural form: change the link for the item with title
'Configuration' from '/reference/configuration' to '/references/configuration',
change the link for 'CLI Commands' from '/reference/cli' to '/references/cli',
and change the link for 'Frontmatter Fields' from '/reference/frontmatter' to
'/references/frontmatter' so they match the existing '/references/' paths used
elsewhere.
---
Nitpick comments:
In `@docs/getting-started/introduction.mdx`:
- Line 28: Summary: The word "markdown" should use title-style capitalization
for consistency. Fix: locate the sentence containing "Tell your AI to write
markdown, run `zpress dev`, done." (the paragraph starting "**Built for the
vibe.**") and change "markdown" to "Markdown"; scan the same document for other
instances of "markdown" and apply consistent capitalization where used as the
technology name.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 1e1d9194-aa5e-4123-a101-9e3da6fe9f71
📒 Files selected for processing (2)
docs/getting-started/introduction.mdxzpress.config.ts
Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/references/icons/colors.mdx (1)
67-67: Small wording polish for readability.Consider reducing repeated sentence starts (“Feature … Feature …”) to make this paragraph scan cleaner.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/references/icons/colors.mdx` at line 67, Merge the two repetitive sentences into one concise sentence to avoid repeating "Feature" — e.g., rewrite the paragraph so it reads along the lines of: "Feature cards on the home page accept a plain icon string identifier and do not support { id, color } objects; feature icons inherit their native or currentColor styling." Update the sentence in the docs/references/icons/colors.mdx paragraph that currently starts with "Feature cards on the home page..." to this single, clearer line.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/references/icons/colors.mdx`:
- Line 67: Merge the two repetitive sentences into one concise sentence to avoid
repeating "Feature" — e.g., rewrite the paragraph so it reads along the lines
of: "Feature cards on the home page accept a plain icon string identifier and do
not support { id, color } objects; feature icons inherit their native or
currentColor styling." Update the sentence in the
docs/references/icons/colors.mdx paragraph that currently starts with "Feature
cards on the home page..." to this single, clearer line.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b62c45aa-9df8-46d2-97a6-976cfeaf9437
📒 Files selected for processing (11)
docs/references/icons/colors.mdxdocs/references/icons/overview.mdxdocs/references/icons/technology/databases.mdxdocs/references/icons/technology/frameworks.mdxdocs/references/icons/technology/infrastructure.mdxdocs/references/icons/technology/integrations.mdxdocs/references/icons/technology/languages.mdxdocs/references/icons/technology/overview.mdxdocs/references/icons/technology/tooling.mdxpackage.jsonzpress.config.ts
✅ Files skipped from review due to trivial changes (6)
- docs/references/icons/technology/databases.mdx
- docs/references/icons/technology/infrastructure.mdx
- package.json
- docs/references/icons/technology/overview.mdx
- docs/references/icons/technology/frameworks.mdx
- docs/references/icons/technology/languages.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/references/icons/technology/tooling.mdx
- docs/references/icons/technology/integrations.mdx
- docs/references/icons/overview.mdx
- zpress.config.ts
Rewrite and restructure documentation site: add landing pages, update configuration reference, expand built-in component docs, and add new concept/guide pages. Fix lint errors across packages (ternaries, curly braces, replaceAll, JSDoc). Add port/vscode flags to dev/serve commands, simplify section landing config, and add vscode release workflow. Co-Authored-By: Claude <noreply@anthropic.com>
Add VSCode extension settings for theme override (zpress.theme), color mode override (zpress.theme.mode), and server port (zpress.server.port). Overrides are passed as CLI flags and applied at runtime without modifying the user's zpress.config. Clamp color mode against theme-supported modes so dark-only themes ignore light/toggle. Unify midnight and arcade CSS to single dark look (no "less dark" variant). Fix autoOpen to use in-editor preview panel instead of opening system browser. Co-Authored-By: Claude <noreply@anthropic.com>
- fix(packages/cli): setup template uses correct field names (title/path/include) - fix(packages/cli): serveSite uses getPort for port fallback - fix(packages/core): warn on OpenAPI parse failures instead of silent swallow - fix(packages/core): image filename collision via hash-prefixed output names - fix(packages/core): parallel image I/O via Promise.all - fix(packages/core): HTML-escape op.path in sidebar text - fix(packages/core): remove orphaned JSDoc, add mutation comments - fix(packages/core): landing card props built immutably with match() - fix(packages/ui): mermaid securityLevel strict, escapeHtml single-quote - fix(packages/ui): handlePointerDown reads transform from ref (stable callback) - fix(packages/ui): body overflow save/restore in fullscreen - fix(extensions/vscode): port 0 handled correctly with != null check - docs: fix broken /concepts/machine-readable link to /concepts/llm-output - docs: landing field documented as boolean to match schema - docs: workspaces examples use WorkspaceCategory structure, remove phantom category field - docs: WorkspaceCategory.description marked optional - docs: nav example references existing page - docs: isolated -> standalone in intro and CLI reference Co-Authored-By: Claude <noreply@anthropic.com>
Update docs for accuracy and consistency, refactor vscode extension with new resource assets, improve core sync/resolve logic, and refresh UI components including card icons and desktop window rendering. Co-Authored-By: Claude <noreply@anthropic.com>
The test fixture used `link` and `from` which are not valid Section schema fields. Replaced with `path` which is a recognized property. Co-Authored-By: Claude <noreply@anthropic.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.
Summary
check,draft) and config fields (theme,actions,seo,sidebar)Changes
References
Section/Workspacetype names and fields, add missing top-level fields (theme,actions,seo,sidebar), fixlandingandsidebarLayoutomissions, updateicon/iconColorfield structurecheckanddraftcommand docs, documentbuild --check/--no-checkflagConcepts
discoverywrapper from Section example, add'default'sort strategy, fix default sort behavior descriptionprefixnotpath), correcticon/iconColorusage, fix link pathsicon,iconColor,card,landingfieldsswitcherdefault description, add references sectionGetting Started
Icons & Misc
/reference/→/references/link paths throughoutTest plan
zpress buildto confirm no deadlink warningspackages/config/src/types.tsSummary by CodeRabbit
Documentation
New Features
Chores