@plutocms/docs 0.0.0-stage → 0.16.0

package/.gitattributes

@@ -0,0 +1 @@
+test/fixtures/** -text

package/.prettierignore

@@ -0,0 +1,5 @@
+
+# Generated by release-please.
+CHANGELOG.md
+# MDC test fixtures: the tests compare their exact text.
+test/fixtures/

package/CHANGELOG.md

@@ -0,0 +1,186 @@
+# Changelog
+
+## [0.16.0](https://github.com/plutocms/docs/compare/v0.15.0...v0.16.0) (2026-10-31)
+
+
+### Features
+
+* block sources and component meta mapping for the editor ([#75](https://github.com/plutocms/docs/issues/75)) ([cc04cf0](https://github.com/plutocms/docs/commit/cc04cf044112b6d4432817711c1e8ed34cce1b7e))
+* discover editor blocks from definePlutoBlock in components/content ([#78](https://github.com/plutocms/docs/issues/78)) ([0ce82b9](https://github.com/plutocms/docs/commit/0ce82b9672b276c6b50edf6f647fd42490595c84))
+
+## [0.15.0](https://github.com/plutocms/nuxt-content/compare/v0.14.0...v0.15.0) (2026-10-31)
+
+
+### ⚠ BREAKING CHANGES
+
+* the package is now @plutocms/docs. The config key plutoNuxtContent is now plutoDocs. The i18n namespace nuxt-content is now docs. The env var PLUTO_NUXT_CONTENT_PATH is not used in this repo.
+
+### Features
+
+* rename the package to @plutocms/docs ([#71](https://github.com/plutocms/nuxt-content/issues/71)) ([b480cfa](https://github.com/plutocms/nuxt-content/commit/b480cfacca3df143ce5844ec26f46679e5ea293b))
+
+## [0.14.0](https://github.com/plutocms/nuxt-content/compare/v0.13.0...v0.14.0) (2026-10-31)
+
+
+### Features
+
+* the docs types go to the pages nav group, with a navGroup option ([#65](https://github.com/plutocms/nuxt-content/issues/65)) ([8d366e7](https://github.com/plutocms/nuxt-content/commit/8d366e76558d7a9b163aa6c9fca77a9eaa2a9358))
+
+## [0.13.0](https://github.com/plutocms/nuxt-content/compare/v0.12.3...v0.13.0) (2026-10-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* the layer extends @plutocms/core >=0.38.0, not @plutocms/pluto. PLUTO_PLUTO_PATH is now PLUTO_CORE_PATH.
+
+### Features
+
+* extend @plutocms/core ([#59](https://github.com/plutocms/nuxt-content/issues/59)) ([a5ca2b9](https://github.com/plutocms/nuxt-content/commit/a5ca2b9a1b340d6ceb3d00487414d098c9fae683))
+
+## [0.12.3](https://github.com/plutocms/nuxt-content/compare/v0.12.2...v0.12.3) (2026-10-29)
+
+
+### Bug Fixes
+
+* **deps:** accept every 0.x version of the [@plutocms](https://github.com/plutocms) packages; shared CI and the update workflow ([#42](https://github.com/plutocms/nuxt-content/issues/42)) ([91b2f58](https://github.com/plutocms/nuxt-content/commit/91b2f58e1f9fa6a47866df6d84e89b59552d9af4))
+
+## [0.12.2](https://github.com/plutocms/nuxt-content/compare/v0.12.1...v0.12.2) (2026-10-29)
+
+
+### Bug Fixes
+
+* **deps:** use @plutocms/pluto 0.34 ([#40](https://github.com/plutocms/nuxt-content/issues/40)) ([000c153](https://github.com/plutocms/nuxt-content/commit/000c1538d414bc95483a4293f826a747d47820d5))
+
+## [0.12.1](https://github.com/plutocms/nuxt-content/compare/v0.12.0...v0.12.1) (2026-10-29)
+
+
+### Bug Fixes
+
+* **deps:** use @plutocms/pluto 0.33 ([#38](https://github.com/plutocms/nuxt-content/issues/38)) ([ca54a9f](https://github.com/plutocms/nuxt-content/commit/ca54a9fb8b2bfa8ce5349fbcbd488941413064d6))
+
+## [0.12.0](https://github.com/plutocms/nuxt-content/compare/v0.11.0...v0.12.0) (2026-10-29)
+
+
+### Features
+
+* **mdc:** use the Markdown code editor of core ([#36](https://github.com/plutocms/nuxt-content/issues/36)) ([b11c355](https://github.com/plutocms/nuxt-content/commit/b11c3550c165373a7080bf4583ceddd4b104d2ae))
+
+## [0.11.0](https://github.com/plutocms/nuxt-content/compare/v0.10.0...v0.11.0) (2026-10-28)
+
+
+### Features
+
+* **editor:** block list layout, scroll area, preview loading, Markdown footer, canonical classes and Prettier ([#33](https://github.com/plutocms/nuxt-content/issues/33)) ([6743ca9](https://github.com/plutocms/nuxt-content/commit/6743ca98f044641fc4ac8074270efb1b6ce33e75))
+
+## [0.10.0](https://github.com/plutocms/nuxt-content/compare/v0.9.0...v0.10.0) (2026-10-28)
+
+
+### Features
+
+* **editor:** show the block row controls on hover ([#30](https://github.com/plutocms/nuxt-content/issues/30)) ([5a2faf5](https://github.com/plutocms/nuxt-content/commit/5a2faf56461cc944670931eafea1cbac705623a4))
+
+
+### Bug Fixes
+
+* **deps:** use @plutocms/pluto 0.29 ([#32](https://github.com/plutocms/nuxt-content/issues/32)) ([423c6db](https://github.com/plutocms/nuxt-content/commit/423c6dba402f67ad8306651e377c5697041d9ddb))
+
+## [0.9.0](https://github.com/plutocms/nuxt-content/compare/v0.8.0...v0.9.0) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* the layer reads `plutoGithub`, not `plutoCms`. An app that sets `plutoCms` options sets `plutoGithub` now.
+
+### Features
+
+* use the GitHub names of pluto 0.28 ([#28](https://github.com/plutocms/nuxt-content/issues/28)) ([f3f2ee7](https://github.com/plutocms/nuxt-content/commit/f3f2ee7dc08a0f5872eab82fb02e7271cded822f))
+
+## [0.8.0](https://github.com/plutocms/nuxt-content/compare/v0.7.0...v0.8.0) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* `/api/_pluto/nuxt-content/:type/{page,navigation,surround}` is now `/api/pluto/v1/nuxt-content/:type/{page,navigation,surround}`, and the answer is `{ data }`. A site that uses the composables needs no change.
+
+### Features
+
+* serve the layer routes on the public API of Pluto, and make the docs pages public ([#26](https://github.com/plutocms/nuxt-content/issues/26)) ([9c1ddd9](https://github.com/plutocms/nuxt-content/commit/9c1ddd982d7c24ff22e70337a345a76ddeb63131))
+
+## [0.7.0](https://github.com/plutocms/nuxt-content/compare/v0.6.0...v0.7.0) (2026-10-27)
+
+
+### ⚠ BREAKING CHANGES
+
+* the default render mode is now 'hybrid'. Content pages must not be prerendered in hybrid or runtime mode. Set `render: 'build'` to keep a fully static site. Needs @plutocms/pluto with `markPublicRead` and `readFile`.
+
+### Features
+
+* render the pages in hybrid mode by default, with build and runtime modes ([#24](https://github.com/plutocms/nuxt-content/issues/24)) ([44efefe](https://github.com/plutocms/nuxt-content/commit/44efefec130c9a48744ec79eba0f454399f5560b))
+
+## [0.6.0](https://github.com/plutocms/nuxt-content/compare/v0.5.0...v0.6.0) (2026-10-27)
+
+
+### Features
+
+* use the admin bar buttons of core, and shorten the README ([#22](https://github.com/plutocms/nuxt-content/issues/22)) ([568f54b](https://github.com/plutocms/nuxt-content/commit/568f54b3f0a73e0346c44f2aec44e6c34c0320fe))
+
+## [0.5.0](https://github.com/plutocms/nuxt-content/compare/v0.4.1...v0.5.0) (2026-10-26)
+
+
+### Features
+
+* **deps:** use @plutocms/pluto 0.24 ([#20](https://github.com/plutocms/nuxt-content/issues/20)) ([acb7195](https://github.com/plutocms/nuxt-content/commit/acb71955bdf7f2fb18d545e6281aaef50cc9fc23))
+
+## [0.4.1](https://github.com/plutocms/nuxt-content/compare/v0.4.0...v0.4.1) (2026-10-26)
+
+
+### Bug Fixes
+
+* **editor:** type the editor for the sites that type-check the layer ([#18](https://github.com/plutocms/nuxt-content/issues/18)) ([c7b08bb](https://github.com/plutocms/nuxt-content/commit/c7b08bbb92e7417487303d599ba42820c0d07059))
+
+## [0.4.0](https://github.com/plutocms/nuxt-content/compare/v0.3.2...v0.4.0) (2026-10-26)
+
+
+### Features
+
+* add the visual block editor and a hybrid Markdown mode ([#16](https://github.com/plutocms/nuxt-content/issues/16)) ([22c8c5e](https://github.com/plutocms/nuxt-content/commit/22c8c5e7f7f745ced4ef01d85160b08aa5749d7a))
+
+## [0.3.2](https://github.com/plutocms/nuxt-content/compare/v0.3.1...v0.3.2) (2026-10-25)
+
+
+### Bug Fixes
+
+* **i18n:** use the nuxt-content namespace, so core translates the labels ([#14](https://github.com/plutocms/nuxt-content/issues/14)) ([4c44e3c](https://github.com/plutocms/nuxt-content/commit/4c44e3ce43d8a7d47e9ce0cd20477c41a676ba39))
+
+## [0.3.1](https://github.com/plutocms/nuxt-content/compare/v0.3.0...v0.3.1) (2026-10-25)
+
+
+### Bug Fixes
+
+* **i18n:** translate the doc type in the admin ([#12](https://github.com/plutocms/nuxt-content/issues/12)) ([2ff7034](https://github.com/plutocms/nuxt-content/commit/2ff70343257ecf912be2e39a94a73a80a9c8aeee))
+
+## [0.3.0](https://github.com/plutocms/nuxt-content/compare/v0.2.0...v0.3.0) (2026-10-25)
+
+
+### Features
+
+* add New Page and Edit Page to the admin bar ([#9](https://github.com/plutocms/nuxt-content/issues/9)) ([c5fe6ad](https://github.com/plutocms/nuxt-content/commit/c5fe6ad5ebc4a868aacfe8013647b325fc3898a7))
+
+## [0.2.0](https://github.com/plutocms/nuxt-content/compare/v0.1.0...v0.2.0) (2026-10-25)
+
+
+### Features
+
+* **deps:** use @plutocms/pluto 0.20 and default to no post type ([#6](https://github.com/plutocms/nuxt-content/issues/6)) ([b4fb0f0](https://github.com/plutocms/nuxt-content/commit/b4fb0f044da3411162047503e9ac8ab23df48001))
+
+## 0.1.0 (2026-10-25)
+
+
+### Features
+
+* add the Nuxt Content layer with a docs preset ([90db635](https://github.com/plutocms/nuxt-content/commit/90db63534eead5ed108d01304eae3092072a44dc))
+
+
+### Miscellaneous Chores
+
+* start the release line at 0.1.0 ([36cfc78](https://github.com/plutocms/nuxt-content/commit/36cfc7892ae904e2bc7014da643c1fd3e5b18d1a))

package/FEATURES.md

@@ -0,0 +1,34 @@
+# Features
+
+This file lists every implemented feature of this project. Each entry links to a skill file
+with full detail, so this file stays short.
+
+See the workspace-level `CLAUDE.md` (one directory up) for the delegation, writing, and git
+policies shared by every project here.
+
+- Docs setup: the `plutoDocs` module, its options, and the plugins that register
+  the types. See @.claude/skills/docs-setup/SKILL.md.
+- Docs preset: the `docs` page type, the frontmatter hooks, and tree order. See
+  @.claude/skills/docs-preset/SKILL.md.
+- MDC field: the `mdc` field widget. Visual mode (the block editor) and Markdown mode (with the
+  Insert menu of snippets). See @.claude/skills/mdc-field/SKILL.md.
+- Render modes: `plutoDocs.render` is `'hybrid'` (default: the build data, and the repository for the
+  pages that changed after the build), `'build'` or `'runtime'`. A build manifest, server routes, `.navigation.yml`
+  and frontmatter parity, and the composables `usePlutoContentPage`, `usePlutoContentNavigation` and
+  `usePlutoContentSurround` that hide the mode. The layer routes are on the public API
+  (`/api/pluto/v1/docs/:type/{page,navigation,surround}`, `{ data }` answers), and the docs type is
+  public on core's `/api/pluto/v1/content/<type>`. See @.claude/skills/docs-setup/SKILL.md.
+- Page links: the View link of the form (`previewUrl`), the "New Page" and "Edit Page" buttons of the admin bar (core draws them from `adminBar`),
+  `contentRoutePath`, `contentEditPath`, and `usePlutoContentEditLink`. See
+  @.claude/skills/page-links/SKILL.md.
+- Admin bar offset: CSS that keeps a Nuxt UI header under the Pluto admin bar. See
+  @.claude/skills/admin-bar-offset/SKILL.md.
+- Block model: the pure model of the visual block editor (parse, serialize, edit, history,
+  presets, registry, preview protocol). The text of an unedited block stays byte for byte. See
+  @.claude/skills/block-model/SKILL.md.
+- Block discovery: a component in `components/content/` (the app or a layer) that calls
+  `definePlutoBlock({...})` becomes a block in the palette, with its props and slots read from its
+  TypeScript types. Opt-in. The option `plutoDocs.blocks.discover` turns it off. See
+  @.claude/skills/block-model/SKILL.md.
+- Block editor: the visual editor for the page body. A live preview, the block list, the palette, and
+  the controls of the selected block, with no raw MDC. See @.claude/skills/block-editor/SKILL.md.

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# Docs layer for Pluto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Edit the Markdown pages of a [Nuxt Content](https://content.nuxt.com) site in the Pluto admin,
+with a visual block editor and a live preview. The pages stay Markdown files in your GitHub
+repository, and each save is a commit.
+
+**Docs:** [Docs layer](https://pluto.vulmix.dev/docs/layers/docs) ·
+[Edit pages visually](https://pluto.vulmix.dev/docs/guides/edit-pages-visually)
+
+## Install
+
+```bash
+npm install @plutocms/docs
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  extends: [['@plutocms/docs', { install: true }]],
+
+  plutoDocs: {
+    types: [{ preset: 'docs', name: 'doc', source: '' }],
+  },
+})
+```
+
+The layer brings `@plutocms/core`. It needs Node 22.5 or newer. The docs show the rest of the
+setup: the collections, the CSS entry, `PlutoRoot`, and the GitHub App.
+
+## What you get
+
+- A `docs` page type for nested, numbered Markdown pages.
+- A visual block editor with a live preview, and a Markdown mode.
+- Your own components in the palette: call `definePlutoBlock({ label, icon })` in a component of `components/content/`. The props and slots come from its TypeScript types.
+- Hybrid render mode (default): a save shows on the site at once, with no wait for a build. Build and runtime modes are options.
+- "New Page" and "Edit Page" in the admin bar, and an "Edit in admin" link for the public page.
+- The pages on the public API of Pluto (`/api/pluto/v1/content/<type>`), for a site in any stack.
+
+## License
+
+MIT

package/app/assets/css/pluto-layer.css

@@ -0,0 +1,40 @@
+/*
+ * The docs layer's CSS. It is not a Tailwind entry.
+ *
+ * The app's CSS entry owns the one Tailwind build of the app. It imports this
+ * file through `#build/pluto.css`. This file imports no Tailwind, adds no
+ * @theme and no @source. See the single-tailwind-build skill in pluto.
+ *
+ * It offsets a Nuxt UI site (a docs site) under the Pluto admin bar. The bar
+ * is `position: fixed`, 40px high, and shows on public pages for signed-in
+ * staff. Pluto marks <html> with `data-pluto-admin-bar` while the bar shows.
+ *
+ * The site sets its header height in `--pluto-site-header-height` (default
+ * 4rem). Without the bar nothing changes. With the bar:
+ * - the page moves down by the bar height (`body` padding), so no content is
+ *   under the bar;
+ * - `--ui-header-height` grows by the bar height. The Nuxt UI parts that stick
+ *   below the header read it: the page aside, the table of contents, the
+ *   mobile menu. They then stick below the bar and the header;
+ * - `UHeader` (class `pluto-header-offset`) keeps its own height and sticks
+ *   below the bar.
+ * The admin pages (`data-pluto-admin` on <html>) never use these rules.
+ */
+:root:not([data-pluto-admin]) {
+  --pluto-site-header-height: 4rem;
+}
+
+:root[data-pluto-admin-bar]:not([data-pluto-admin]) {
+  --ui-header-height: calc(
+    var(--pluto-site-header-height) + var(--pluto-admin-bar-height)
+  );
+}
+
+:root[data-pluto-admin-bar]:not([data-pluto-admin]) body {
+  padding-top: var(--pluto-admin-bar-height);
+}
+
+:root[data-pluto-admin-bar]:not([data-pluto-admin]) .pluto-header-offset {
+  top: var(--pluto-admin-bar-height);
+  height: var(--pluto-site-header-height);
+}

package/app/components/Pluto/Docs/Blocks/PlutoBlockEditor.vue

@@ -0,0 +1,165 @@
+<script setup lang="ts">
+// The component layer. Only the two editor roots import it, so it stays out of the public pages.
+import componentBlocks from '#pluto-docs/blocks'
+// The visual block editor: the canvas of the 'canvas' form layout. The canvas
+// shows the live preview of the page. The block list goes in the left panel,
+// and the controls of the selected block go in the right panel (a tab of the
+// form's aside). The widget keeps all the state, so the panels are slots of
+// this one component tree. The value is the Markdown text of the page body. A
+// block that no edit touched keeps its bytes, so opening and saving a page
+// with no edit changes nothing. See the block-editor skill.
+import PlutoBlockInspector from './PlutoBlockInspector.vue'
+import PlutoBlockOutline from './PlutoBlockOutline.vue'
+import PlutoBlockPalette from './PlutoBlockPalette.vue'
+import PlutoBlockPreviewFrame from './PlutoBlockPreviewFrame.vue'
+
+const props = defineProps<{
+  modelValue: string
+  disabled?: boolean
+  mode: 'visual' | 'markdown'
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  'update:mode': [mode: 'visual' | 'markdown']
+}>()
+
+const { t } = usePlutoI18n()
+const form = usePlutoContentForm()
+const blockSources = usePlutoBlockSources(componentBlocks)
+
+const editor = createPlutoBlockEditor({
+  source: () => props.modelValue,
+  emit: (value) => emit('update:modelValue', value),
+  sources: blockSources,
+})
+provide(plutoBlockEditorKey, editor)
+
+// The front matter for the preview header: the item without the body and the internal `_` keys.
+const frontmatter = computed<Record<string, unknown>>(() => {
+  const item = form?.item.value ?? {}
+  return Object.fromEntries(
+    Object.entries(item).filter(
+      ([key]) => key !== 'body' && !key.startsWith('_')
+    )
+  )
+})
+
+// A selection brings the Block tab forward (and opens the panel on a narrow screen). On a narrow
+// screen the block list is a slideover. A choice in it closes the slideover, so the controls show.
+const wide = useMediaQuery('(min-width: 1024px)')
+watch(
+  () => editor.selection.value,
+  (selection) => {
+    if (!selection) {
+      return
+    }
+    if (!wide.value && selection.source === 'ui') {
+      document
+        .querySelector('[data-block-outline]')
+        ?.closest('[role="dialog"]')
+        ?.querySelector<HTMLElement>('button[data-slot="close"]')
+        ?.click()
+    }
+    form?.openPanel('block')
+  }
+)
+
+// One undo stack for the page: Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z (or Ctrl+Y). They act while the
+// focus is in the editor (a panel or the canvas). Elsewhere (the Page tab) the browser keeps its own undo.
+function onKeydown(event: KeyboardEvent) {
+  if (props.disabled || !(event.ctrlKey || event.metaKey) || event.altKey) {
+    return
+  }
+  const target = event.target
+  const inside =
+    target instanceof Element &&
+    (target.closest('[data-pluto-block-ui]') ||
+      target.closest('[data-block-canvas]'))
+  const key = event.key.toLowerCase()
+  if (!inside) {
+    return
+  }
+  const row =
+    target instanceof Element
+      ? target.closest<HTMLElement>('[data-block-row]')?.dataset.blockRow
+      : undefined
+  if (key === 'z' && !event.shiftKey) {
+    event.preventDefault()
+    editor.undo()
+  } else if ((key === 'z' && event.shiftKey) || key === 'y') {
+    event.preventDefault()
+    editor.redo()
+  } else {
+    return
+  }
+  // A list row that moves in the DOM loses the focus. Give it back, so the next shortcut works.
+  nextTick(() => {
+    if (
+      row &&
+      (!document.activeElement || document.activeElement === document.body)
+    ) {
+      document
+        .querySelector<HTMLElement>(`[data-block-row="${CSS.escape(row)}"]`)
+        ?.focus()
+    }
+  })
+}
+
+onMounted(() => document.addEventListener('keydown', onKeydown, true))
+onBeforeUnmount(() => document.removeEventListener('keydown', onKeydown, true))
+</script>
+
+<template>
+  <div class="flex h-full min-h-0 flex-col" data-block-canvas>
+    <div v-if="editor.error.value" class="p-4">
+      <UAlert
+        :title="t('docs.editor.parseErrorTitle')"
+        :description="t('docs.editor.parseError')"
+        :actions="[
+          {
+            label: t('docs.editor.switchToMarkdown'),
+            color: 'neutral',
+            variant: 'outline',
+            onClick: () => emit('update:mode', 'markdown'),
+          },
+        ]"
+        color="warning"
+        variant="subtle"
+        icon="i-lucide-triangle-alert"
+      />
+    </div>
+
+    <PlutoBlockPreviewFrame
+      v-else
+      :frontmatter="frontmatter"
+      class="min-h-0 flex-1"
+    />
+
+    <template v-if="!editor.error.value">
+      <PlutoContentCanvasPanel
+        id="blocks"
+        :label="t('docs.editor.blocks')"
+        side="left"
+        icon="i-lucide-blocks"
+      >
+        <PlutoBlockOutline
+          :mode="mode"
+          :disabled="disabled"
+          @update:mode="emit('update:mode', $event)"
+        />
+      </PlutoContentCanvasPanel>
+
+      <PlutoContentCanvasPanel
+        id="block"
+        :label="t('docs.editor.blockTab')"
+        side="right"
+        icon="i-lucide-square-pen"
+      >
+        <PlutoBlockInspector :disabled="disabled" />
+      </PlutoContentCanvasPanel>
+
+      <PlutoBlockPalette />
+    </template>
+  </div>
+</template>