From 639645016aab758b4ed7bd8c4bbd2c4d5641c368 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 2 Nov 2026 12:25:44 +0000 Subject: [PATCH 1/4] fix(cache): bump CONTENT_PARSER_VERSION for comark 0.8 The layer moved from comark 0.7 to 0.8, whose heading ids are flat, without a new cache namespace. A push webhook handled by a still-live old deployment could warm content:v5: with nested ids that the new deployment then serves. Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30 --- server/utils/cache.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/server/utils/cache.ts b/server/utils/cache.ts index c492074..72455cf 100644 --- a/server/utils/cache.ts +++ b/server/utils/cache.ts @@ -17,7 +17,7 @@ function runtimeCacheDriver(base: string, ttl?: number): Driver { * Bump when content parser/plugin configuration, relevant parser dependencies, or cached derived * data changes. Keeping this explicit lets unrelated deployments reuse immutable content artifacts. */ -export const CONTENT_PARSER_VERSION = 'v5' +export const CONTENT_PARSER_VERSION = 'v6' /** * A ref pinned via `withRef()` is treated as immutable, so it can be cached for a long time. From e0c9a5512ca36f421e7076b669efcb0927048bfd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 2 Nov 2026 12:25:44 +0000 Subject: [PATCH 2/4] fix(lint): accept only the Nuxt UI components the layer makes global The layer registers only UButton and UPageHero globally, but lint.mjs accepted every u- component, so ::u-alert passed and rendered as a raw element. Both now read the list from utils/markdown-globals.mjs, and the playground no longer says any Nuxt UI component works. Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30 --- lint.mjs | 5 +++-- modules/config/index.ts | 4 ++-- playground/content/2.writing/3.components.md | 2 +- utils/markdown-globals.mjs | 6 ++++++ 4 files changed, 12 insertions(+), 5 deletions(-) create mode 100644 utils/markdown-globals.mjs diff --git a/lint.mjs b/lint.mjs index 2acf49c..aa483ea 100644 --- a/lint.mjs +++ b/lint.mjs @@ -9,6 +9,7 @@ import { fileURLToPath } from 'node:url' import { comarkContent } from 'comark-content' import fs from 'comark-content/sources/fs' import emoji from 'comark/plugins/emoji' +import { globalNuxtUiComponents } from './utils/markdown-globals.mjs' const kebab = (/** @type {string} */ name) => name.replace(/[A-Z]/g, (c, i) => (i ? '-' : '') + c.toLowerCase()) @@ -23,11 +24,11 @@ function componentsIn(/** @type {string} */ dir) { 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`. +// `app/components/content/`, plus the Nuxt UI components the layer makes global, 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'))}`), + ...globalNuxtUiComponents.map(name => kebab(name)), ] // Each page's URL, mapped to its file the way comark-content derives the URL from it. diff --git a/modules/config/index.ts b/modules/config/index.ts index 03b421b..02ed096 100644 --- a/modules/config/index.ts +++ b/modules/config/index.ts @@ -3,6 +3,7 @@ import { addServerPlugin, createResolver, defineNuxtModule, useLogger } from '@n import { defu } from 'defu' import type { ModuleOptions as AgentDiscoveryOptions } from 'nuxt-agent-discovery' import { getGitBranch, getGitEnv, getGitRoot, getLocalGitInfo } from '../../utils/git' +import { globalNuxtUiComponents } from '../../utils/markdown-globals.mjs' import { getPackageJsonMetadata, inferSiteURL, resolveContentDir } from './utils' const logger = useLogger('comark-docs') @@ -138,8 +139,7 @@ export default defineNuxtModule({ // Extend Nuxt UI components to make them global and usable in markdown by consumers. nuxt.hook('components:extend', (components) => { - const globalComponents = ['UButton', 'UPageHero'] - for (const component of globalComponents) { + for (const component of globalNuxtUiComponents) { const entry = components.find((c) => c.pascalName === component) if (!entry) continue entry.global = true diff --git a/playground/content/2.writing/3.components.md b/playground/content/2.writing/3.components.md index eb85995..e9e3b3f 100644 --- a/playground/content/2.writing/3.components.md +++ b/playground/content/2.writing/3.components.md @@ -129,7 +129,7 @@ Other useful ones: `::tabs` with `:::tabs-item{label="..."}` children, `::collap ## Nuxt UI components -Any Nuxt UI component works with the `u-` prefix. The [landing page](/writing/landing-page) uses this for its hero: +`UButton` and `UPageHero` work with the `u-` prefix, since the layer registers them globally. The [landing page](/writing/landing-page) uses them for its hero: ::code-preview ::u-button diff --git a/utils/markdown-globals.mjs b/utils/markdown-globals.mjs new file mode 100644 index 0000000..c5e3cf5 --- /dev/null +++ b/utils/markdown-globals.mjs @@ -0,0 +1,6 @@ +// @ts-check +/** + * The Nuxt UI components the layer registers globally, so Markdown can use them with the `u-` prefix, + * such as `::u-button`. `modules/config` registers them and `lint.mjs` accepts them. + */ +export const globalNuxtUiComponents = ['UButton', 'UPageHero'] From 5d162a5c859d1bbe1eec3a8f4d48dab9b61003b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 2 Nov 2026 12:30:41 +0000 Subject: [PATCH 3/4] docs: list only the global Nuxt UI components in the components intro Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30 --- playground/content/2.writing/3.components.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/playground/content/2.writing/3.components.md b/playground/content/2.writing/3.components.md index e9e3b3f..7cc1de9 100644 --- a/playground/content/2.writing/3.components.md +++ b/playground/content/2.writing/3.components.md @@ -8,7 +8,7 @@ Beyond plain [Markdown](/writing/markdown), pages can use Vue components through Three kinds of components are available in docs pages: - **Nuxt UI prose components** — callouts, tabs, steps, and code widgets, available without any prefix. -- **Nuxt UI components** — any [Nuxt UI](https://ui.nuxt.com) component, with the `u-` prefix (`::u-button`). +- **Nuxt UI components** — the ones the layer registers globally, [`UButton`](https://ui.nuxt.com/docs/components/button) and [`UPageHero`](https://ui.nuxt.com/docs/components/page-hero), with the `u-` prefix (`::u-button`). - **Layer components** — `Mermaid`, `CodeExplorer`, and `Browser`, injected by the docs page. ## Prose components From 80238a8954bf27d22dc7d881be194418e13ea6a6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Chopin?= Date: Mon, 2 Nov 2026 12:38:54 +0000 Subject: [PATCH 4/4] refactor: re-export Nuxt UI's button instead of global u- components The layer made UButton and UPageHero global so Markdown could use ::u-button and ::u-page-hero. Like LandingHero.ts, content/Button.ts and content/landing/Button.ts now re-export Nuxt UI's button, so ::button resolves through each page's own map and nothing is global. The lint preset no longer needs a separate u- list, and the playground uses ::button and ::landing-hero. Amp-Thread-ID: https://ampcode.com/threads/T-01a18c64-cf17-72b6-afc0-24d664666b30 --- app/components/content/Button.ts | 2 ++ app/components/content/landing/Button.ts | 2 ++ app/pages/index.vue | 7 +------ lint.mjs | 4 +--- modules/config/index.ts | 10 ---------- playground/content/2.writing/3.components.md | 8 ++++---- playground/content/2.writing/4.landing-page.md | 8 ++++---- utils/markdown-globals.mjs | 6 ------ 8 files changed, 14 insertions(+), 33 deletions(-) create mode 100644 app/components/content/Button.ts create mode 100644 app/components/content/landing/Button.ts delete mode 100644 utils/markdown-globals.mjs diff --git a/app/components/content/Button.ts b/app/components/content/Button.ts new file mode 100644 index 0000000..59bb04f --- /dev/null +++ b/app/components/content/Button.ts @@ -0,0 +1,2 @@ +// `::button` is Nuxt UI's button. +export { default } from '@nuxt/ui/components/Button.vue' diff --git a/app/components/content/landing/Button.ts b/app/components/content/landing/Button.ts new file mode 100644 index 0000000..59bb04f --- /dev/null +++ b/app/components/content/landing/Button.ts @@ -0,0 +1,2 @@ +// `::button` is Nuxt UI's button. +export { default } from '@nuxt/ui/components/Button.vue' diff --git a/app/pages/index.vue b/app/pages/index.vue index cd2b1a1..0498976 100644 --- a/app/pages/index.vue +++ b/app/pages/index.vue @@ -1,10 +1,5 @@