feat: ship a comark-linter config for sites

README.md

@@ -43,6 +43,25 @@ From there, the docs cover everything:
 - [Architecture](https://docs-template.comark.dev/concepts/architecture) and [versioned previews](https://docs-template.comark.dev/concepts/versioned-previews)
 - [Deploying on Vercel](https://docs-template.comark.dev/deployment/vercel) — webhook, Ignored Build Step, content rollback
 
+## Linting content
+
+`lint.mjs` is a [comark-linter](https://comark-ui.onmax.me/lint/) config that knows the components the layer renders and resolves links to your pages the way comark-content does, so it reports unknown components, unclosed blocks, and broken links and anchors in `content/`:
+
+```bash
+pnpm add -D comark-linter
+```
+
+```ts
+// comark-lint.config.ts
+export { default } from 'comark-docs/lint.mjs'
+```
+
+```bash
+pnpm comark-lint "content/**/*.md"
+```
+
+Run it from the site's root, where `content/` and `comark-lint.config.ts` are. It knows the components the layer renders: Nuxt UI's prose components and those in the layer's `app/components/content/`.
+
 ## Agent Skills
 
 Drop skills into a `skills/` directory at the app root and [nuxt-agent-discovery](https://github.com/benjamincanac/nuxt-agent-discovery) serves them at `/.well-known/skills/`, following the [Agent Skills Discovery RFC](https://github.com/cloudflare/agent-skills-discovery-rfc) (v0.1). Users install them with:

app/components/content/landing/LandingHero.ts

@@ -0,0 +1,2 @@
+// `::landing-hero` is Nuxt UI's page hero.
+export { default } from '@nuxt/ui/components/PageHero.vue'

app/components/landing/LandingHeroDemo.vue → app/components/content/landing/LandingHeroDemo.vue

@@ -1,6 +1,6 @@
 <script setup lang="ts">
 import rangi from 'comark/plugins/rangi'
-import { geistTheme } from '../../../utils/geist'
+import { geistTheme } from '../../../../utils/geist'
 
 const props = defineProps<{
   /** Markdown source: shown highlighted in the source tab, rendered live in the output tab. */

app/pages/[...slug].vue

@@ -2,114 +2,17 @@
 import { joinURL } from 'ufo'
 import type { NavigationItem } from 'comark-content'
 import { Mermaid } from '@comark/nuxt/plugins/mermaid'
-import {
-  ProseA,
-  ProseAccordion,
-  ProseAccordionItem,
-  ProseBadge,
-  ProseBlockquote,
-  ProseCallout,
-  ProseCard,
-  ProseCardGroup,
-  ProseCaution,
-  ProseCode,
-  ProseCodeCollapse,
-  ProseCodeGroup,
-  ProseCodeIcon,
-  ProseCodePreview,
-  ProseCodeTree,
-  ProseCollapsible,
-  ProseEm,
-  ProseField,
-  ProseFieldGroup,
-  ProseH1,
-  ProseH2,
-  ProseH3,
-  ProseH4,
-  ProseHr,
-  ProseIcon,
-  ProseImg,
-  ProseKbd,
-  ProseLi,
-  ProseNote,
-  ProseOl,
-  ProseP,
-  ProsePre,
-  ProsePrompt,
-  ProseScript,
-  ProseSteps,
-  ProseStrong,
-  ProseTable,
-  ProseTabs,
-  ProseTabsItem,
-  ProseTbody,
-  ProseTd,
-  ProseTh,
-  ProseThead,
-  ProseTip,
-  ProseTr,
-  ProseUl,
-  ProseWarning,
-} from '#components'
-import CodeExplorer from '../components/CodeExplorer.vue'
-import Browser from '../components/Browser.vue'
+import * as prose from '@nuxt/ui/components/prose'
 
 definePageMeta({
   path: '/:slug(.+)',
 })
 
 // Resolve prose eagerly with the docs route instead of the global async components.
 const components = {
-  ProseA,
-  ProseAccordion,
-  ProseAccordionItem,
-  ProseBadge,
-  ProseBlockquote,
-  ProseCallout,
-  ProseCard,
-  ProseCardGroup,
-  ProseCaution,
-  ProseCode,
-  ProseCodeCollapse,
-  ProseCodeGroup,
-  ProseCodeIcon,
-  ProseCodePreview,
-  ProseCodeTree,
-  ProseCollapsible,
-  ProseEm,
-  ProseField,
-  ProseFieldGroup,
-  ProseH1,
-  ProseH2,
-  ProseH3,
-  ProseH4,
-  ProseHr,
-  ProseIcon,
-  ProseImg,
-  ProseKbd,
-  ProseLi,
-  ProseNote,
-  ProseOl,
-  ProseP,
-  ProsePre,
-  ProsePrompt,
-  ProseScript,
-  ProseSteps,
-  ProseStrong,
-  ProseTable,
-  ProseTabs,
-  ProseTabsItem,
-  ProseTbody,
-  ProseTd,
-  ProseTh,
-  ProseThead,
-  ProseTip,
-  ProseTr,
-  ProseUl,
-  ProseWarning,
+  ...prose,
+  ...byFileName(import.meta.glob('../components/content/*.{vue,ts}', { eager: true, import: 'default' })),
   Mermaid,
-  CodeExplorer,
-  Browser,
 }
 
 const { toc } = useAppConfig()
@@ -139,8 +42,8 @@
 
 const surroundLinks = computed(() => findSurroundLinks(navigation?.value, selfPath.value))
 
 const fm = computed<Record<string, any>>(() => page.value?.data ?? {})
 const tocLinks = computed<any[]>(() => (page.value?.meta as any)?.toc?.links ?? [])
 // Landing-style pages (e.g. /ecosystem) have no headings to list, so the aside would only hold the
 // page actions and squeeze the content. Docs pages keep it for the menu and page actions.
 const showAside = computed(() => layout?.value !== 'page' || tocLinks.value.length > 0)

app/pages/index.vue

@@ -1,24 +1,9 @@
 <script setup lang="ts">
-import LandingHero from '@nuxt/ui/components/PageHero.vue'
-import LandingStack from '../components/landing/LandingStack.vue'
-import LandingTabs from '../components/landing/LandingTabs.vue'
-import LandingFeatures from '../components/landing/LandingFeatures.vue'
-import LandingFeatureCard from '../components/landing/LandingFeatureCard.vue'
-import LandingFaq from '../components/landing/LandingFaq.vue'
-import LandingCta from '../components/landing/LandingCta.vue'
-import LandingHeroDemo from '../components/landing/LandingHeroDemo.vue'
 import Button from '@nuxt/ui/components/Button.vue'
 
 const landingComponents = {
-  LandingHero,
-  LandingStack,
-  LandingTabs,
-  LandingFeatures,
-  LandingFeatureCard,
-  LandingFaq,
-  LandingCta,
-  LandingHeroDemo,
-  Button
+  ...byFileName(import.meta.glob('../components/content/landing/*.{vue,ts}', { eager: true, import: 'default' })),
+  Button,
 }
 
 const content = useDocsContent()
@@ -35,7 +20,7 @@
   return p ? { ...p, nodes: prefixTreeLinks(p.nodes, content.value.routeBase) } : p
 })
 
 const fm = computed<Record<string, any>>(() => page.value?.data ?? {})
 
 // Keep branch/commit previews out of search, same as DocsPage.
 useRobotsRule(computed(() => (content.value.mode === 'prod' ? 'index, follow' : 'noindex, nofollow')))

app/utils/content-components.ts

@@ -0,0 +1,13 @@
+import type { Component } from 'vue'
+
+/**
+ * Names the layer's Markdown components after their file: `content/CodeExplorer.vue` renders
+ * `::code-explorer`. Each page globs its own folder (docs pages `content/`, the landing page
+ * `content/landing/`) and passes the result to `MarkdownDocument`, so none is global and neither
+ * page loads the other's, such as the landing demo's Markdown parser. `lint.mjs` reads both folders.
+ */
+export function byFileName(modules: Record<string, unknown>): Record<string, Component> {
+  return Object.fromEntries(
+    Object.entries(modules).map(([path, component]) => [path.slice(path.lastIndexOf('/') + 1).replace(/\.\w+$/, ''), component as Component]),
+  )
+}

eslint.config.mjs

@@ -34,16 +34,16 @@ export default createConfigForNuxt({
   .append({
     // Page, layout and error component names come from Nuxt's file-based routing —
     // `index.vue`, `docs.vue`, `[...slug].vue` are the framework's naming, not ours.
-    // `Browser.vue` is exempt for a different reason: it's addressed from markdown
-    // (`::browser`), so its name is part of the content API.
+    // `app/components/content/` is exempt for a different reason: Markdown addresses those
+    // components by name (`::browser`), so their names are part of the content API.
     files: [
       'app/pages/**/*.vue',
       'playground/app/pages/**/*.vue',
       'app/layouts/**/*.vue',
       'playground/app/layouts/**/*.vue',
       'app/error.vue',
       'playground/app/error.vue',
-      'app/components/Browser.vue',
+      'app/components/content/**/*.vue',
     ],
     rules: {
       'vue/multi-word-component-names': 'off',

lint.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+// A comark-linter config for sites extending this layer. Run `comark-lint` from the site's root:
+//   comark-lint "content/**/*.md"
+// next to a `comark-lint.config.ts` that re-exports it: `export { default } from 'comark-docs/lint.mjs'`.
+// Plain JavaScript, since Node won't strip types from a file in node_modules.
+import { readdirSync } from 'node:fs'
+import { basename, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { comarkContent } from 'comark-content'
+import fs from 'comark-content/sources/fs'
+import emoji from 'comark/plugins/emoji'
+
+const kebab = (/** @type {string} */ name) => name.replace(/[A-Z]/g, (c, i) => (i ? '-' : '') + c.toLowerCase())
+
+/** The kebab-case names of the components in a folder and its subfolders. */
+function componentsIn(/** @type {string} */ dir) {
+  return readdirSync(dir, { recursive: true, encoding: 'utf8' })
+    .map(file => basename(file).match(/^(\w+)\.(vue|ts)$/)?.[1])
+    .filter(name => name !== undefined)
+    .map(name => kebab(name))
+}
+
+const nuxtUi = dirname(fileURLToPath(import.meta.resolve('@nuxt/ui/components/Button.vue')))
+
+// What the pages pass to `MarkdownDocument`: Nuxt UI's prose components and the layer's
+// `app/components/content/`, plus every Nuxt UI component with the `u-` prefix, such as `::u-button`.
+const components = [
+  ...componentsIn(`${nuxtUi}/prose`),
+  ...componentsIn(fileURLToPath(new URL('app/components/content', import.meta.url))),
+  ...readdirSync(nuxtUi).filter(file => file.endsWith('.vue')).map(file => `u-${kebab(basename(file, '.vue'))}`),
+]
+
+// Each page's URL, mapped to its file the way comark-content derives the URL from it.
+const pages = new Map()
+for (const item of await comarkContent({ source: fs('content') }).list()) {
+  pages.set(item.path, `content/${item.meta.stem}${item.meta.extension}`)
+}
+
+/** @type {import('comark-linter').Config} */
+export default {
+  components,
+  // The layer parses `:smile:` shortcodes as emoji, not as inline components.
+  plugins: [emoji()],
+  links: {
+    // Guides link a local dev server on purpose, for readers running it.
+    skip: ['localhost'],
+    routes: path => pages.get(path.replace(/\/$/, '') || '/'),
+  },
+}

nuxt.config.ts

@@ -27,6 +27,13 @@ export default defineNuxtConfig({
     'nuxt-agent-discovery',
   ],
   ignore: ['content/**'],
+  components: [
+    // Markdown components keep the name Markdown addresses them by: `CodeExplorer`, not `ContentCodeExplorer`.
+    // Not global: the pages pass them to `MarkdownDocument` themselves (see `app/utils/content-components.ts`).
+    // Relative to this layer's srcDir: `~` would resolve to the site's.
+    { path: 'components/content', pathPrefix: false },
+    'components',
+  ],
   // Publishes Nuxt's `nuxt.*` diagnostics channels; server/plugins/tracer.ts turns them into OTel spans.
   tracingChannel: true,
   ui: { content: true, prose: true },

package.json

@@ -24,6 +24,7 @@
     "nuxt.config.ts",
     "nuxt.schema.ts",
     "index.d.ts",
+    "lint.mjs",
     "README.md"
   ],
   "scripts": {
@@ -32,7 +33,8 @@
     "build": "nuxt build playground",
     "generate": "nuxt generate playground",
     "typecheck": "nuxt typecheck playground",
-    "lint": "eslint .",
+    "lint": "eslint . && pnpm lint:content",
+    "lint:content": "cd playground && comark-lint \"content/**/*.md\"",
     "lint:fix": "eslint . --fix",
     "test": "vitest run --project unit",
     "test:e2e": "vitest run --project e2e",
@@ -99,6 +101,7 @@
     "@opentelemetry/resources": "^2.12.0",
     "@opentelemetry/sdk-trace-base": "^2.12.0",
     "@opentelemetry/sdk-trace-node": "^2.12.0",
+    "comark-linter": "^0.7.6",
     "es-module-lexer": "^3.0.2",
     "eslint": "^10.13.0",
     "nuxt": "^4.6.2",

playground/comark-lint.config.ts

@@ -0,0 +1,2 @@
+// Lints this playground with the config the layer ships to sites.
+export { default } from '../lint.mjs'

playground/content/2.writing/3.components.md

@@ -206,7 +206,7 @@ default-value: index.md
 | `default-value` | `string` | first file | Path of the file selected on load. |
 
 ::warning
-The server only fetches from your own content repository by default. To embed another repository, add it to [`comarkDocs.codeExplorer.allowRepos`](/getting-started/configuration#nuxtconfigts-comarkdocs-options).
+The server only fetches from your own content repository by default. To embed another repository, add it to [`comarkDocs.codeExplorer.allowRepos`](/getting-started/configuration#comarkdocs-options).
 ::
 
 ## Browser

playground/content/2.writing/4.landing-page.md

@@ -219,4 +219,4 @@ Props: `id` (optional anchor). Slots: `title`, `description`, `links`.
 
 ## Structured data
 
-Beyond the FAQ JSON-LD, the landing page can emit a [schema.org SoftwareApplication](https://schema.org/SoftwareApplication) identity. Configure it once in `app.config.ts` under [`docs.schemaOrg`](/getting-started/configuration#appconfigts-all-keys); nothing is emitted when unset.
+Beyond the FAQ JSON-LD, the landing page can emit a [schema.org SoftwareApplication](https://schema.org/SoftwareApplication) identity. Configure it once in `app.config.ts` under [`docs.schemaOrg`](/getting-started/configuration#all-keys); nothing is emitted when unset.

playground/content/3.concepts/1.architecture.md

@@ -85,4 +85,4 @@ A request for a page that doesn't exist returns a real HTTP 404 with a short Mar
 
 ## No redeploys for content
 
-Since content never ships in the build, a content-only push doesn't need a deployment at all. On Vercel, an [Ignored Build Step](/deployment/vercel#setup-skip-builds-for-content-pushes) cancels builds for pushes that only touch `content/` — the webhook handles those. Code pushes build and deploy as usual.
+Since content never ships in the build, a content-only push doesn't need a deployment at all. On Vercel, an [Ignored Build Step](/deployment/vercel#skip-builds-for-content-pushes) cancels builds for pushes that only touch `content/` — the webhook handles those. Code pushes build and deploy as usual.

playground/content/4.deployment/1.vercel.md

@@ -83,7 +83,7 @@ Copy the full commit SHA for the content version you want to serve. In the store
 }
 ```
 
-New server renders now read content from that commit. Pages already cached by ISR update as they expire, which takes up to the configured [`comarkDocs.isr`](/getting-started/configuration#nuxtconfigts-comarkdocs-options) duration (300 seconds by default).
+New server renders now read content from that commit. Pages already cached by ISR update as they expire, which takes up to the configured [`comarkDocs.isr`](/getting-started/configuration#comarkdocs-options) duration (300 seconds by default).
 
 ### Remove or move the pin
 
@@ -99,7 +99,7 @@ Replace `contentSha` with another full commit SHA to move the pin. Delete the it
 
 The layer generates ISR route rules for every top-level content section, the landing page, previews, and the machine-readable routes (`/raw/**`, `/llms.txt`, `/llms-full.txt`, `/sitemap.md`, `/rss.xml`, `/openapi.json`). Pages expire after 300 seconds by default, or immediately when the webhook purges them.
 
-Tune or disable this with [`comarkDocs.isr`](/getting-started/configuration#nuxtconfigts-comarkdocs-options) in `nuxt.config.ts`. Your own `routeRules` take precedence over the generated ones.
+Tune or disable this with [`comarkDocs.isr`](/getting-started/configuration#comarkdocs-options) in `nuxt.config.ts`. Your own `routeRules` take precedence over the generated ones.
 
 Client-side navigation is unaffected by that expiration window: it fetches each page's data separately (`_payload.json`), which the browser revalidates on every navigation rather than caching for the ISR duration — so a webhook purge is visible there immediately too, at the cost of a conditional request the edge answers without re-sending the body.