Skip to content

docs: lint docs content with comark-linter - #546

Merged
atinux merged 4 commits into
mainfrom
docs/comark-lint
Nov 2, 2026
Merged

atinux merged 4 commits into
mainfrom
docs/comark-lint

Conversation

@atinux

@atinux atinux commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Written by an AI agent (Amp) on behalf of @atinux.

Lints docs/content with comark-linter and fixes what it finds. pnpm lint now runs it, so CI checks the docs on every PR.

Linter

Fixes

  • 112 anchors. comark.dev still renders with comark 0.7's nested heading ids. The bumped layer brings comark-content 0.4 and comark 0.8, whose ids are flat (as comarkdown/comark-content#137 handled for its docs). 65 of these links were already broken on comark.dev (older #code-… ids), and the other 46 work there today only through nested ids. Each one now points at the flat id of the heading it meant. I derived that by parsing each target page with headingIds: 'nested' and with flat ids, then pairing the headings. Renamed headings were mapped by hand: render-options-* became the renderHtml/renderAnsi options, and #comarkplugin became ComarkPlugin<TMeta, TFrontmatter>. With the bumped layer running in nuxt dev, every changed link's fragment exists as an id in the rendered page (111 links on changed lines across 15 pages, 0 missing).
  • 7 u- blocks. The layer no longer makes UButton and UPageHero global, so the landing and ecosystem pages use ::landing-hero and :::button, which the layer re-exports. The lint flagged all 7 after the bump. The landing hero looks the same, and the ecosystem page's buttons render.
  • 9 ::tab-item blocks in the installation and Twoslash pages become Nuxt UI's tabs-item. tab-item only rendered because the tabs read any child's label and icon, leaving 7 raw <tab-item> elements on the installation page. The gap-0 on those tabs made up for that element's margin, so it goes too. The tabs look the same in the dev server and switch frameworks.

Note: the layer bump changes heading ids site-wide, so outside links to nested anchors on comark.dev stop matching after this deploys.

pnpm lint passes. AGENTS.md mentions the docs lint.

Summary by CodeRabbit

  • Documentation
    • Corrected links across guides and reference pages so they lead to the matching sections.
    • Updated package setup tabs and refreshed components on the landing and ecosystem pages; destinations and configuration remain unchanged.
  • Chores
    • Added documentation lint checks for broken links, unknown components, and unclosed blocks to the project’s lint command.
    • Configured documentation checks to recognize site components and routes.

Bumps comark-docs to 0640755, which ships a comark-linter preset (lint.mjs): the components the layer renders, and links resolved through comark-content. docs/comark-lint.config.ts adds the site's own app/components/prose/ components and its /play and /stream Vue pages, and pnpm lint runs it, so CI checks the docs on every PR.

Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30
The bumped layer renders with comark 0.8, whose heading ids are flat, so 112 links to nested or older code- ids are pointed at the flat id of the heading each meant. The 9 tab-item blocks become Nuxt UI's tabs-item, without the gap-0 that made up for the raw element's margin.

Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30
@atinux
atinux requested a review from farnabaz as a code owner November 2, 2026 12:01
@coldtea-pr-lens

Copy link
Copy Markdown

Note

The title starts with docs:, so PR Lens left this pull request undrawn. Comment @pr-lens draw to draw it

github.comment.notice: false in .github/pr-lens.yml turns this note off

@vercel

vercel Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
comark Ready Ready Preview Nov 2, 2026 2:39pm UTC
8 Skipped Deployments
Project Deployment Actions Updated
comark-binding Skipped Skipped Nov 2, 2026 2:39pm UTC
comark-json-render Skipped Skipped Nov 2, 2026 2:39pm UTC
comark-nextjs Skipped Skipped Nov 2, 2026 2:39pm UTC
comark-nuxt Skipped Skipped Nov 2, 2026 2:39pm UTC
comark-svelte Skipped Skipped Nov 2, 2026 2:39pm UTC
comark-sveltekit Skipped Skipped Nov 2, 2026 2:39pm UTC
comark-twoslash Skipped Skipped Nov 2, 2026 2:39pm UTC
comark-vue Skipped Skipped Nov 2, 2026 2:39pm UTC

@coderabbitai

coderabbitai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

Caution

Review failed

The pull request is closed.

Recent review info
Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: f04fb73c-cf81-40cd-a371-dcd79b4e4728
Commits

Reviewing files that changed from the base of the PR and between 3312b7b and bd59562.

Files ignored due to path filters: 1
  • pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml
Files selected for processing: 3
  • docs/content/9.ecosystem.md
  • docs/content/index.md
  • docs/package.json

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Walkthrough

The PR adds a configured documentation linter and runs it from the root lint command. It updates documentation tabs, component names, and internal links to match current component syntax and heading anchors.

Changes: Documentation lint and content

Layer / File(s) Summary
Docs linter setup
docs/comark-lint.config.ts, docs/package.json, pnpm-workspace.yaml
Adds a docs lint command and linter dependency. The configuration extends the docs preset with site component names and route matching.
Documentation markup and links
docs/content/1.getting-started/1.installation.md, docs/content/7.kb/4.twoslash.md, docs/content/9.ecosystem.md, docs/content/index.md, docs/content/10.use-cases/*.md, docs/content/11.compare/*.md, docs/content/3.rendering/*.md, docs/content/4.plugins/**/*.md, docs/content/5.reference/0.render.md
Updates tab directives and component names. Updates internal links to current heading anchors.
Root lint integration and instructions
package.json, AGENTS.md
Adds docs-site linting to the root lint command and documents the docs lint command, checks, and configuration.

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Other

Possibly related issues

Possibly related PRs

  • comarkdown/comark#521 — This PR continues the comark-docs dependency update and adjusts content for the resulting heading IDs and component syntax.

Suggested reviewers: larbish

Merge Risk: Low · up to fd5fb

The /stream page loses the intended layout and styling for several landing sections; adding their loaders is a small fix before merging.

Pre-merge checks: Passed 5
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the main change: adding comark-linter to lint the documentation content.
Docstring Coverage Passed No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentat…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Docstring Coverage

Explanation

No eligible functions found in the changed files. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 0 functions across 1 files. (3 skipped: 3 unsupported.)

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

Share

@pkg-pr-new

pkg-pr-new Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

comark

npm i https://pkg.pr.new/comark@546

@comark/angular

npm i https://pkg.pr.new/@comark/angular@546

@comark/ansi

npm i https://pkg.pr.new/@comark/ansi@546

@comark/html

npm i https://pkg.pr.new/@comark/html@546

@comark/nuxt

npm i https://pkg.pr.new/@comark/nuxt@546

@comark/react

npm i https://pkg.pr.new/@comark/react@546

@comark/svelte

npm i https://pkg.pr.new/@comark/svelte@546

@comark/vue

npm i https://pkg.pr.new/@comark/vue@546

commit: fd5fb92

@codspeed

codspeed Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Merging this PR will not alter performance

1 warning

⚠️ 3 benchmarks are dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

✅ 41 untouched benchmarks


Comparing docs/comark-lint (fd5fb92) with main (41409df)

Open in CodSpeed

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

Comment thread docs/comark-lint.config.ts Resolved
Comment thread docs/package.json Resolved
comarkdown/comark-docs#79 bumps the layer's content cache version, so a deployment still serving comark 0.7's nested heading ids can't warm the cache the new one reads. It also re-exports Nuxt UI's button instead of making UButton and UPageHero global, so the landing and ecosystem pages use ::landing-hero and :::button.

Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30
@vercel
vercel Bot temporarily deployed to Preview – comark-nuxt November 2, 2026 14:02 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-sveltekit November 2, 2026 14:02 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-svelte November 2, 2026 14:02 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-json-render November 2, 2026 14:02 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-twoslash November 2, 2026 14:02 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-binding November 2, 2026 14:02 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-vue November 2, 2026 14:02 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-nextjs November 2, 2026 14:02 Inactive

@coderabbitai coderabbitai Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Fix comments: Fix CodeRabbit comments on this PR

Comment thread docs/content/index.md Resolved
/stream renders content/index.md through its own components manifest. ::u-page-hero worked there only because the layer made UPageHero global, and the layer's LandingHero isn't, so map it to Nuxt UI's PageHero.

Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30
@vercel
vercel Bot temporarily deployed to Preview – comark-binding November 2, 2026 14:36 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-vue November 2, 2026 14:36 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-json-render November 2, 2026 14:36 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-sveltekit November 2, 2026 14:36 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-twoslash November 2, 2026 14:36 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-svelte November 2, 2026 14:36 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-nuxt November 2, 2026 14:36 Inactive
@vercel
vercel Bot temporarily deployed to Preview – comark-nextjs November 2, 2026 14:36 Inactive
@atinux
atinux merged commit f2cb864 into main Nov 2, 2026
17 of 18 checks passed
@atinux
atinux deleted the docs/comark-lint branch November 2, 2026 14:45

This branch was previously deployed

8 inactive deployments
Preview – comark-nextjs — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Preview – comark-nuxt — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Preview – comark-svelte — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Preview – comark-twoslash — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Preview – comark-sveltekit — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Preview – comark-json-render — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Preview – comark-vue — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Preview – comark-binding — fd5fb92b Deployed Nov 2, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants