@plutocms/docs 0.0.0-stage → 0.15.0

package/i18n/locales/en.json

@@ -0,0 +1,253 @@
+{
+  "docs": {
+    "capabilities": {
+      "write": "Create and edit pages",
+      "delete": "Delete pages"
+    },
+    "mdc": {
+      "insert": "Insert",
+      "placeholder": "Write the page in Markdown. Use the Insert menu for MDC components."
+    },
+    "snippets": {
+      "note": "Note",
+      "tip": "Tip",
+      "warning": "Warning",
+      "caution": "Caution",
+      "callout": "Callout",
+      "codeGroup": "Code group",
+      "tabs": "Tabs",
+      "steps": "Steps",
+      "cardGroup": "Card group",
+      "accordion": "Accordion",
+      "fieldGroup": "Field group",
+      "kbd": "Keyboard key",
+      "icon": "Icon",
+      "codeFile": "Code block with file name"
+    },
+    "blocks": {
+      "kinds": {
+        "text": "Text",
+        "code": "Code",
+        "raw": "Markdown",
+        "table": "Table",
+        "textDescription": "A title and a text.",
+        "tableDescription": "Rows and columns of text.",
+        "codeDescription": "A block of code with colors."
+      },
+      "groups": {
+        "text": "Text",
+        "callouts": "Callouts",
+        "layout": "Layout",
+        "code": "Code",
+        "landing": "Landing page",
+        "site": "Site"
+      },
+      "props": {
+        "icon": "Icon",
+        "to": "Link",
+        "target": "Open the link in",
+        "title": "Title",
+        "color": "Color",
+        "level": "Heading level",
+        "accordionType": "Open items",
+        "label": "Label",
+        "description": "Description",
+        "sync": "Sync key",
+        "name": "Name",
+        "openText": "Text to open",
+        "closeText": "Text to close",
+        "fieldType": "Type",
+        "required": "Required",
+        "value": "Value",
+        "headline": "Headline",
+        "orientation": "Layout direction",
+        "reverse": "Reverse the order",
+        "variant": "Style",
+        "size": "Size",
+        "spotlight": "Spotlight effect"
+      },
+      "slots": {
+        "default": "Content",
+        "headline": "Headline",
+        "title": "Title",
+        "description": "Text",
+        "links": "Buttons",
+        "features": "Features"
+      },
+      "note": {
+        "label": "Note",
+        "description": "A blue box for extra information."
+      },
+      "tip": {
+        "label": "Tip",
+        "description": "A green box with a useful tip."
+      },
+      "warning": {
+        "label": "Warning",
+        "description": "An orange box for something to be careful about."
+      },
+      "caution": {
+        "label": "Caution",
+        "description": "A red box for a risk or a breaking change."
+      },
+      "callout": {
+        "label": "Callout",
+        "description": "A box with an icon and a color that you choose."
+      },
+      "card": {
+        "label": "Card",
+        "description": "A box with a title, an icon and a link."
+      },
+      "card-group": {
+        "label": "Card group",
+        "description": "Cards side by side in a grid."
+      },
+      "steps": {
+        "label": "Steps",
+        "description": "A numbered list of steps with headings."
+      },
+      "accordion": {
+        "label": "Accordion",
+        "description": "Questions that open and close."
+      },
+      "accordion-item": {
+        "label": "Accordion item",
+        "description": "One question and its answer."
+      },
+      "tabs": {
+        "label": "Tabs",
+        "description": "Content in tabs, one tab at a time."
+      },
+      "tabs-item": {
+        "label": "Tab",
+        "description": "One tab of a group of tabs."
+      },
+      "collapsible": {
+        "label": "Collapsible",
+        "description": "Text that the reader opens with a click."
+      },
+      "field-group": {
+        "label": "Field group",
+        "description": "A list of fields, for an API or a setting."
+      },
+      "field": {
+        "label": "Field",
+        "description": "One field with a name, a type and a text."
+      },
+      "code-group": {
+        "label": "Code group",
+        "description": "Code blocks in tabs, for example one per package manager."
+      },
+      "code-collapse": {
+        "label": "Code that collapses",
+        "description": "A long code block that the reader opens."
+      },
+      "badge": {
+        "label": "Badge",
+        "description": "A small label inside a text."
+      },
+      "kbd": {
+        "label": "Keyboard key",
+        "description": "A keyboard key inside a text."
+      },
+      "icon": {
+        "label": "Icon",
+        "description": "An icon inside a text."
+      },
+      "u-page-hero": {
+        "label": "Hero",
+        "description": "The big title at the top of a landing page."
+      },
+      "u-page-section": {
+        "label": "Page section",
+        "description": "A section with a title, a text and features."
+      },
+      "u-page-feature": {
+        "label": "Feature",
+        "description": "An icon, a title and a short text."
+      },
+      "u-page-card": {
+        "label": "Page card",
+        "description": "A card for a landing page, with a title and a text."
+      },
+      "u-page-grid": {
+        "label": "Card grid",
+        "description": "A grid that holds page cards."
+      },
+      "u-page-c-t-a": {
+        "label": "Call to action",
+        "description": "A box that asks the reader to do something."
+      },
+      "u-button": {
+        "label": "Button",
+        "description": "A button that links to a page."
+      }
+    },
+    "preview": {
+      "title": "Page preview",
+      "parseError": "This block could not be read for the preview.",
+      "blockError": "This block could not show in the preview.",
+      "notShown": "This block does not show in the preview. It still works on the page."
+    },
+    "editor": {
+      "previewTitle": "Preview of the page",
+      "previewLoading": "Loading the preview…",
+      "previewFailedTitle": "The preview did not load",
+      "previewFailed": "The page preview did not answer. You can still edit the blocks. Check that the site has the preview page, then try again.",
+      "previewRetry": "Try again",
+      "addBlock": "Add a block",
+      "addBlockDescription": "Pick a block to add to the page.",
+      "searchBlocks": "Search blocks…",
+      "noBlocks": "No block found.",
+      "mode": "Editor",
+      "visual": "Visual",
+      "markdown": "Markdown",
+      "blocks": "Blocks",
+      "blockTab": "Block",
+      "undo": "Undo",
+      "redo": "Redo",
+      "add": "Add",
+      "moveUp": "Move up",
+      "moveDown": "Move down",
+      "addBelow": "Add a block below",
+      "duplicate": "Duplicate",
+      "delete": "Delete",
+      "edited": "Changed",
+      "expand": "Show the blocks inside {name}",
+      "collapse": "Hide the blocks inside {name}",
+      "blockActions": "Actions for {name}",
+      "addTo": "Add to {name}",
+      "emptyTitle": "This page has no blocks yet",
+      "emptyDescription": "Add a text, a note or a card to start.",
+      "blockPanel": "Block settings",
+      "nothingSelectedTitle": "No block selected",
+      "nothingSelected": "Click a block in the preview or in the list to change it.",
+      "selectParent": "Back to {name}",
+      "rawNote": "This is the Markdown of the block. A change here replaces the block.",
+      "rawLabel": "Markdown of the block",
+      "textLabel": "Text of the block",
+      "textPlaceholder": "Write here…",
+      "language": "Language",
+      "languageHelp": "For the colors, for example ts.",
+      "fileName": "File name",
+      "fileNameHelp": "Shows above the code.",
+      "code": "Code",
+      "tableNote": "A table is a Markdown block. Edit the cells in the box. A visual table editor is planned.",
+      "rawBlockNote": "This block has Markdown that the visual editor does not change. You can edit it as Markdown.",
+      "content": "Content",
+      "settings": "Settings",
+      "advanced": "Advanced",
+      "slotEmpty": "Nothing here yet.",
+      "editAsMarkdown": "Edit as Markdown",
+      "backToControls": "Back to the controls",
+      "applyMarkdown": "Apply",
+      "default": "Default",
+      "iconHelp": "An icon name, for example i-lucide-rocket.",
+      "linkPlaceholder": "/page or https://…",
+      "parseErrorTitle": "The visual editor cannot open this page",
+      "parseError": "The Markdown has a part that the visual editor cannot read. Use the Markdown editor to fix it.",
+      "switchToMarkdown": "Open the Markdown editor",
+      "addItem": "Add {name}"
+    }
+  }
+}

package/i18n/locales/pt-BR.json

@@ -0,0 +1,289 @@
+{
+  "docs": {
+    "capabilities": {
+      "write": "Criar e editar páginas",
+      "delete": "Excluir páginas"
+    },
+    "mdc": {
+      "insert": "Inserir",
+      "placeholder": "Escreva a página em Markdown. Use o menu Inserir para os componentes MDC."
+    },
+    "snippets": {
+      "note": "Nota",
+      "tip": "Dica",
+      "warning": "Aviso",
+      "caution": "Atenção",
+      "callout": "Destaque",
+      "codeGroup": "Grupo de código",
+      "tabs": "Abas",
+      "steps": "Passos",
+      "cardGroup": "Grupo de cartões",
+      "accordion": "Acordeão",
+      "fieldGroup": "Grupo de campos",
+      "kbd": "Tecla",
+      "icon": "Ícone",
+      "codeFile": "Bloco de código com nome de arquivo"
+    },
+    "blocks": {
+      "kinds": {
+        "text": "Texto",
+        "code": "Código",
+        "raw": "Markdown",
+        "table": "Tabela",
+        "textDescription": "Um título e um texto.",
+        "tableDescription": "Linhas e colunas de texto.",
+        "codeDescription": "Um bloco de código com cores."
+      },
+      "groups": {
+        "text": "Texto",
+        "callouts": "Destaques",
+        "layout": "Layout",
+        "code": "Código",
+        "landing": "Página inicial",
+        "site": "Site"
+      },
+      "props": {
+        "icon": "Ícone",
+        "to": "Link",
+        "target": "Abrir o link em",
+        "title": "Título",
+        "color": "Cor",
+        "level": "Nível do título",
+        "accordionType": "Itens abertos",
+        "label": "Rótulo",
+        "description": "Descrição",
+        "sync": "Chave de sincronia",
+        "name": "Nome",
+        "openText": "Texto para abrir",
+        "closeText": "Texto para fechar",
+        "fieldType": "Tipo",
+        "required": "Obrigatório",
+        "value": "Valor",
+        "headline": "Sobretítulo",
+        "orientation": "Direção do layout",
+        "reverse": "Inverter a ordem",
+        "variant": "Estilo",
+        "size": "Tamanho",
+        "spotlight": "Efeito de destaque"
+      },
+      "slots": {
+        "default": "Conteúdo",
+        "headline": "Sobretítulo",
+        "title": "Título",
+        "description": "Texto",
+        "links": "Botões",
+        "features": "Recursos"
+      },
+      "note": {
+        "label": "Nota",
+        "description": "Uma caixa azul para informação extra."
+      },
+      "tip": {
+        "label": "Dica",
+        "description": "Uma caixa verde com uma dica útil."
+      },
+      "warning": {
+        "label": "Aviso",
+        "description": "Uma caixa laranja para algo que pede cuidado."
+      },
+      "caution": {
+        "label": "Atenção",
+        "description": "Uma caixa vermelha para um risco ou uma mudança que quebra."
+      },
+      "callout": {
+        "label": "Destaque",
+        "description": "Uma caixa com ícone e cor à sua escolha."
+      },
+      "card": {
+        "label": "Cartão",
+        "description": "Uma caixa com título, ícone e link."
+      },
+      "card-group": {
+        "label": "Grupo de cartões",
+        "description": "Cartões lado a lado em uma grade."
+      },
+      "steps": {
+        "label": "Passos",
+        "description": "Uma lista numerada de passos com títulos."
+      },
+      "accordion": {
+        "label": "Acordeão",
+        "description": "Perguntas que abrem e fecham."
+      },
+      "accordion-item": {
+        "label": "Item do acordeão",
+        "description": "Uma pergunta e a resposta."
+      },
+      "tabs": {
+        "label": "Abas",
+        "description": "Conteúdo em abas, uma aba por vez."
+      },
+      "tabs-item": {
+        "label": "Aba",
+        "description": "Uma aba de um grupo de abas."
+      },
+      "collapsible": {
+        "label": "Conteúdo recolhível",
+        "description": "Texto que o leitor abre com um clique."
+      },
+      "field-group": {
+        "label": "Grupo de campos",
+        "description": "Uma lista de campos, para uma API ou uma configuração."
+      },
+      "field": {
+        "label": "Campo",
+        "description": "Um campo com nome, tipo e texto."
+      },
+      "code-group": {
+        "label": "Grupo de código",
+        "description": "Blocos de código em abas, por exemplo um por gerenciador de pacotes."
+      },
+      "code-collapse": {
+        "label": "Código recolhível",
+        "description": "Um bloco de código longo que o leitor abre."
+      },
+      "badge": {
+        "label": "Selo",
+        "description": "Um rótulo pequeno dentro de um texto."
+      },
+      "kbd": {
+        "label": "Tecla",
+        "description": "Uma tecla do teclado dentro de um texto."
+      },
+      "icon": {
+        "label": "Ícone",
+        "description": "Um ícone dentro de um texto."
+      },
+      "u-page-hero": {
+        "label": "Destaque de abertura",
+        "description": "O título grande no topo de uma página inicial."
+      },
+      "u-page-section": {
+        "label": "Seção da página",
+        "description": "Uma seção com título, texto e recursos."
+      },
+      "u-page-feature": {
+        "label": "Recurso",
+        "description": "Um ícone, um título e um texto curto."
+      },
+      "u-page-card": {
+        "label": "Cartão da página",
+        "description": "Um cartão para a página inicial, com título e texto."
+      },
+      "u-page-grid": {
+        "label": "Grade de cartões",
+        "description": "Uma grade que reúne cartões da página."
+      },
+      "u-page-c-t-a": {
+        "label": "Chamada para ação",
+        "description": "Uma caixa que pede uma ação ao leitor."
+      },
+      "u-button": {
+        "label": "Botão",
+        "description": "Um botão que leva a uma página."
+      }
+    },
+    "preview": {
+      "title": "Prévia da página",
+      "parseError": "Não foi possível ler este bloco para a prévia.",
+      "blockError": "Este bloco não pôde aparecer na prévia.",
+      "notShown": "Este bloco não aparece na prévia. Ele continua funcionando na página."
+    },
+    "editor": {
+      "previewTitle": "Prévia da página",
+      "previewLoading": "Carregando a prévia…",
+      "previewFailedTitle": "A prévia não carregou",
+      "previewFailed": "A prévia da página não respondeu. Você ainda pode editar os blocos. Veja se o site tem a página de prévia e tente de novo.",
+      "previewRetry": "Tentar de novo",
+      "addBlock": "Adicionar um bloco",
+      "addBlockDescription": "Escolha um bloco para adicionar à página.",
+      "searchBlocks": "Buscar blocos…",
+      "noBlocks": "Nenhum bloco encontrado.",
+      "mode": "Editor",
+      "visual": "Visual",
+      "markdown": "Markdown",
+      "blocks": "Blocos",
+      "blockTab": "Bloco",
+      "undo": "Desfazer",
+      "redo": "Refazer",
+      "add": "Adicionar",
+      "moveUp": "Mover para cima",
+      "moveDown": "Mover para baixo",
+      "addBelow": "Adicionar um bloco abaixo",
+      "duplicate": "Duplicar",
+      "delete": "Excluir",
+      "edited": "Alterado",
+      "expand": "Mostrar os blocos dentro de {name}",
+      "collapse": "Ocultar os blocos dentro de {name}",
+      "blockActions": "Ações de {name}",
+      "addTo": "Adicionar em {name}",
+      "emptyTitle": "Esta página ainda não tem blocos",
+      "emptyDescription": "Adicione um texto, uma nota ou um cartão para começar.",
+      "blockPanel": "Configurações do bloco",
+      "nothingSelectedTitle": "Nenhum bloco selecionado",
+      "nothingSelected": "Clique em um bloco na prévia ou na lista para alterá-lo.",
+      "selectParent": "Voltar para {name}",
+      "rawNote": "Este é o Markdown do bloco. Uma alteração aqui substitui o bloco.",
+      "rawLabel": "Markdown do bloco",
+      "textLabel": "Texto do bloco",
+      "textPlaceholder": "Escreva aqui…",
+      "language": "Linguagem",
+      "languageHelp": "Para as cores, por exemplo ts.",
+      "fileName": "Nome do arquivo",
+      "fileNameHelp": "Aparece acima do código.",
+      "code": "Código",
+      "tableNote": "Uma tabela é um bloco de Markdown. Edite as células na caixa. Um editor visual de tabela está nos planos.",
+      "rawBlockNote": "Este bloco tem Markdown que o editor visual não altera. Você pode editá-lo como Markdown.",
+      "content": "Conteúdo",
+      "settings": "Configurações",
+      "advanced": "Avançado",
+      "slotEmpty": "Nada aqui ainda.",
+      "editAsMarkdown": "Editar como Markdown",
+      "backToControls": "Voltar para os controles",
+      "applyMarkdown": "Aplicar",
+      "default": "Padrão",
+      "iconHelp": "O nome de um ícone, por exemplo i-lucide-rocket.",
+      "linkPlaceholder": "/pagina ou https://…",
+      "parseErrorTitle": "O editor visual não consegue abrir esta página",
+      "parseError": "O Markdown tem uma parte que o editor visual não consegue ler. Use o editor de Markdown para corrigir.",
+      "switchToMarkdown": "Abrir o editor de Markdown",
+      "addItem": "Adicionar {name}"
+    }
+  },
+  "content": {
+    "doc": {
+      "label": "Página",
+      "labelPlural": "Páginas",
+      "fields": {
+        "title": {
+          "label": "Título"
+        },
+        "slug": {
+          "label": "Caminho",
+          "description": "O caminho do arquivo sem .md, por exemplo 2.core/03.content-model. Um caminho novo move o arquivo."
+        },
+        "description": {
+          "label": "Descrição"
+        },
+        "body": {
+          "label": "Conteúdo"
+        },
+        "navigationTitle": {
+          "label": "Título na navegação"
+        },
+        "navigationIcon": {
+          "label": "Ícone na navegação"
+        },
+        "navigationHidden": {
+          "label": "Ocultar da navegação"
+        },
+        "seoTitle": {
+          "label": "Título para SEO"
+        },
+        "seoDescription": {
+          "label": "Descrição para SEO"
+        }
+      }
+    }
+  }
+}

package/modules/pluto-docs/index.ts

@@ -0,0 +1,123 @@
+import type { PlutoDocsOptions } from './options'
+import { join } from 'node:path'
+import {
+  addServerHandler,
+  createResolver,
+  defineNuxtModule,
+  useLogger,
+} from '@nuxt/kit'
+import { PREVIEW_PATH } from '../../shared/utils/blocks/preview-protocol'
+import { buildContentManifest, manifestModuleSource } from './manifest'
+import { resolvePlutoDocsOptions } from './options'
+
+export type { PlutoDocsOptions, PlutoDocsTypeOptions } from './options'
+
+/** The routes of the run-time render mode, on the public API of Pluto. The composables of the layer call them. */
+export const RUNTIME_ROUTE_BASE = '/api/pluto/v1/docs'
+
+/**
+ * Registers the content types of the docs layer. It is OFF when the
+ * app turns the standalone CMS off (`plutoGithub.enabled: false`). The default
+ * `'auto'` and `true` both count as on. The module only checks the options
+ * and copies them to the public runtime config. The client plugin
+ * (`app/plugins/pluto-docs.ts`) and the Nitro plugin
+ * (`server/plugins/pluto-docs.ts`) of the layer build the types from
+ * that config. See the docs-setup skill.
+ */
+export default defineNuxtModule<PlutoDocsOptions>({
+  meta: { name: 'pluto-docs', configKey: 'plutoDocs' },
+  defaults: { types: [] },
+  setup(options, nuxt) {
+    const logger = useLogger('pluto-docs')
+    const cms = (
+      nuxt.options as { plutoGithub?: { enabled?: boolean | 'auto' } }
+    ).plutoGithub
+
+    const { enabled, render, runtimeMaxAge, types, errors } =
+      resolvePlutoDocsOptions(options, {
+        cmsEnabled: cms?.enabled !== false,
+      })
+
+    for (const error of errors) {
+      logger.error(error)
+    }
+    if (!enabled) {
+      return
+    }
+
+    // The plugins read this key. It is absent when the layer is off.
+    nuxt.options.runtimeConfig.public.plutoDocs = {
+      types,
+      render,
+      runtimeMaxAge,
+    }
+
+    if (render === 'hybrid' || render === 'runtime') {
+      const { resolve } = createResolver(import.meta.url)
+      // The toc rules of Nuxt Content, so the run-time parser makes the same table of contents.
+      const content = (
+        nuxt.options as {
+          content?: {
+            build?: {
+              markdown?: { toc?: { depth?: number; searchDepth?: number } }
+            }
+          }
+        }
+      ).content
+      nuxt.options.runtimeConfig.plutoDocs = {
+        toc: content?.build?.markdown?.toc,
+      } as never
+      for (const name of ['page', 'navigation', 'surround']) {
+        addServerHandler({
+          route: `${RUNTIME_ROUTE_BASE}/:type/${name}`,
+          method: 'get',
+          handler: resolve(`../../server/handlers/${name}.get`),
+        })
+      }
+    }
+
+    // The build manifest: content id → version, for each type. The server compares it with the
+    // store (hybrid). It is a virtual module, so it is part of the server bundle and matches the
+    // pages that Nuxt Content builds in the same run. It is made once, when the bundler first asks.
+    const makeManifest = () => {
+      // The CMS module sets the storage and the content dir. They are known here, after all modules ran.
+      const cmsConfig = nuxt.options.runtimeConfig.public.plutoGithub as
+        { storage?: string; dir?: string } | undefined
+      return buildContentManifest(types, {
+        contentDir: join(nuxt.options.rootDir, cmsConfig?.dir ?? 'content'),
+        storage: cmsConfig?.storage ?? 'github',
+      })
+    }
+
+    const manifestId = '#pluto-docs/manifest'
+    let manifestSource: string | undefined
+    nuxt.hook('nitro:config', (nitroConfig) => {
+      nitroConfig.virtual ||= {}
+      nitroConfig.virtual[manifestId] = () => {
+        if (manifestSource === undefined) {
+          manifestSource = manifestModuleSource(
+            render === 'hybrid' ? makeManifest() : {}
+          )
+        }
+        return manifestSource
+      }
+    })
+
+    // The preview page of the visual editor is a client-only page that no search engine should list.
+    // It is not prerendered, and the response says noindex. An app rule for the same path wins.
+    nuxt.options.routeRules = {
+      [PREVIEW_PATH]: {
+        ssr: false,
+        prerender: false,
+        headers: { 'x-robots-tag': 'noindex, nofollow' },
+      },
+      ...nuxt.options.routeRules,
+    }
+
+    if (!nuxt.options._prepare) {
+      logger.info(
+        `Docs layer on. Types: ${types.map((type) => type.name).join(', ') || 'none'}. Render: ${render}.`
+      )
+    }
+  },
+})