@kirchdev/duxt 0.3.4-dev-main.41-23ded41 → 0.3.5-dev-main.43-3310f4b

package/sources-resolve.ts

@@ -20,6 +20,16 @@ export interface DuxtSource {
    * default URL prefix without declaring two page collections for it.
    */
   content?: boolean;
+  /** Per-source conventions for draft pages and reusable Markdown blocks. */
+  exclude?: { drafts?: string; partials?: string };
+  /**
+   * The Markdown dialect this source was generated in.
+   *
+   * Dialects are layer-owned normalisers, not consumer-supplied transforms:
+   * one compact marker keeps an upstream repository readable without making
+   * its generator emit duxt-specific Markdown.
+   */
+  flavor?: DuxtSourceFlavor;
   /** `owner/name` or a full git URL. Omitted reads the local checkout. */
   repo?: string;
   /**
@@ -30,6 +40,15 @@ export interface DuxtSource {
    * build with "Could not find refs/heads/…".
    */
   refs?: DuxtRef[];
+  /**
+   * Discover release tags to publish as versions.
+   *
+   * Discovery is opt-in: a source still needs to say whether every release,
+   * one release per minor, or one per major belongs in its public URLs. Explicit
+   * `refs` stay available beside this object and override a discovered tag's
+   * label, lifecycle, default and locales.
+   */
+  releases?: DuxtSourceReleases;
   /**
    * Languages this source is available in, beyond the one written in `path`.
    *
@@ -64,6 +83,22 @@ export interface DuxtSource {
   version?: string;
   /** Shown in the version switcher and used in the URL; defaults to the ref. */
   label?: string;
+  /**
+   * What to CALL this source where the site names it to a reader.
+   *
+   * Display only — it never reaches a collection name, a URL prefix, a version
+   * or the ranking, which is what separates it from `label` and `slug`. Those
+   * two are addresses that happen to be readable; this is a name that is
+   * nothing else, so it is free to be prose and free to be translated.
+   *
+   * The one thing no rule can derive. A segment is an abbreviation as often as
+   * it is a word — `tf`, `sdk`, `api` — and a search result labelled with one
+   * tells a reader which URL they are in rather than which project. Unset, the
+   * ladder in `app/utils/search-display.ts` falls back to the segment and then
+   * to the site's own name, so a site that sets nothing is still never shown
+   * the bare `/` this key was added for.
+   */
+  name?: string | Record<string, string>;
   /**
    * Segment used in the URL for this source; defaults to the repository name.
    *
@@ -119,6 +154,9 @@ export interface DuxtSource {
   generated?: DuxtGeneratedSection[];
 }
 
+/** Source dialects the layer understands. */
+export type DuxtSourceFlavor = 'tfplugindocs';
+
 /**
  * Where a version sits in its life.
  *
@@ -156,6 +194,14 @@ export type DuxtRef =
   | ({ branch: string } & DuxtRefOptions)
   | ({ tag: string } & DuxtRefOptions);
 
+/** The release lines a source publishes when it discovers Git tags. */
+export interface DuxtSourceReleases {
+  /** Every release, or the newest release in each minor or major line. */
+  select: 'all' | 'minor' | 'major';
+  /** Include SemVer pre-releases; stable releases are the default. */
+  prereleases?: boolean;
+}
+
 interface DuxtRefOptions {
   /** Shown in the switcher and used in the URL; defaults to the ref name. */
   label?: string;
@@ -269,6 +315,14 @@ export interface DuxtResolvedSource {
   repo?: string;
   /** Version label, when the list has more than one version. */
   version?: string;
+  /**
+   * The source's display name, as the consumer wrote it — see `DuxtSource`.
+   *
+   * Carried through UNRESOLVED, because a locale record cannot be collapsed at
+   * build time: the manifest is one object for every language the site serves,
+   * and `useDuxtConfig` resolves it per request like every other text field.
+   */
+  name?: string | Record<string, string>;
   /** True for the version served without a prefix. */
   isDefault: boolean;
   /**
@@ -298,6 +352,8 @@ export interface DuxtResolvedSource {
   status: DuxtSourceStatus;
   /** Whether the build may read this source's git history. */
   history: boolean;
+  /** The layer-owned Markdown dialect this collection is normalised from. */
+  flavor?: DuxtSourceFlavor;
   /**
    * Present when this collection is a GENERATED SECTION rather than a docs
    * tree — see `resolveGeneratedSections`.
@@ -646,6 +702,7 @@ export function resolveSources(
       prefix,
       repo: segmented(source) ? repoSlug(source) : undefined,
       version,
+      name: source.name,
       isDefault,
       repository: entry.repo ?? source.origin?.repo,
       repositoryUrl: entry.repo
@@ -673,7 +730,8 @@ export function resolveSources(
         'current',
       // A local source is a full checkout already; a remote one has to be
       // unshallowed, which is why it has to be asked for.
-      history: entry.repo ? (source.history ?? false) : true
+      history: entry.repo ? (source.history ?? false) : true,
+      flavor: source.flavor
     });
   }
 

package/sources.ts

@@ -17,6 +17,7 @@ export { repositoryRoot };
 export type {
   DuxtResolvedSource,
   DuxtSource,
+  DuxtSourceFlavor,
   DuxtSourcesOptions
 } from './sources-resolve';
 export { duxtSourceManifest } from './sources-resolve';
@@ -35,12 +36,81 @@ export { PARTIALS_COLLECTION, partialsCollection };
 export const pageSchema = z.object({
   /** Shown beside the entry in the sidebar, the section row and page cards. */
   icon: z.string().optional(),
-  /** `landing` renders the page without the docs chrome. */
+  /** Preserved long enough for the tfplugindocs dialect to normalise it. */
+  page_title: z.string().optional(),
+  /** A tfplugindocs navigation group within its directory category. */
+  subcategory: z.string().optional(),
+  /** Set by a source dialect; useful to navigation consumers, not authors. */
+  category: z.string().optional(),
+  /** `landing` renders the page without the docs shell. */
   layout: z.string().optional(),
   /** The latest release of a generated changelog overview. */
   release: z.string().optional(),
-  /** false hides the page from the navigation. */
-  navigation: z.boolean().optional(),
+  //
+  // `navigation` is NOT declared here, deliberately. Content's own page schema
+  // already carries it — `boolean | { title, description, icon }`, defaulting
+  // to `true` — and a field declared here REPLACES that declaration rather than
+  // adding to it. Redeclaring it as a plain boolean cost two things at once: it
+  // dropped the object form, and it turned a TEXT column holding `'true'` into
+  // a BOOLEAN one holding NULL, which Content's own navigation query then
+  // compares against the string `'false'` and can never match. The page control
+  // that hides a page from the sidebar belongs to Content; the layer reads it
+  // and does not restate it.
+  //
+  // THE PAGE CONTROLS — the parts of the docs shell a page gets to refuse.
+  // What each one means, and how they compose, is `app/utils/page-controls.ts`;
+  // they are declared here because the schema is the gate, and an undeclared
+  // `toc: false` is dropped before the page component could ever read it. Flat
+  // fields rather than one nested object, which was decided: it is what an
+  // author writes in every comparable generator.
+  //
+  // EVERY BOOLEAN CONTROL CARRIES ITS DEFAULT, and that is not decoration.
+  // `z.boolean().optional()` generates a `BOOLEAN` column with no default, so a
+  // page that says nothing stores NULL — and Content casts a boolean column
+  // with `Boolean(value)` on the way back out, on every adapter. `Boolean(null)`
+  // is `false`, so every page read as though it had refused every control, and
+  // search returned nothing at all on every duxt site (#88). A default makes the
+  // column non-null, which is the only place the distinction survives: once the
+  // cast has run, "said nothing" and "said false" are the same value, and no
+  // predicate downstream can tell them apart. `tests/page-schema-database.test.ts`
+  // holds this by reading a page back out of a real database.
+  //
+  /**
+   * `false` drops the contents column; `{ maxDepth }` sets how deep it goes.
+   *
+   * `@nuxtjs/mdc` reads this same key out of the frontmatter and skips building
+   * `body.toc` at all on `false` — the same answer from the other end. The
+   * object form is ours alone: MDC's own `depth` is a count from `h2`, and
+   * `maxDepth` is the heading level an author actually counts.
+   *
+   * The one control with no default, because it needs none: a union is a JSON
+   * column, and Content leaves a JSON NULL alone rather than casting it — so an
+   * unanswered `toc` arrives as `null` and the site's own setting still wins.
+   */
+  toc: z
+    .union([z.boolean(), z.object({ maxDepth: z.number().optional() })])
+    .optional(),
+  /** false hides the trail above the title, whatever `duxt.breadcrumb` says. */
+  breadcrumb: z.boolean().default(true),
+  /** false hides the previous/next pair under the article. */
+  prevNext: z.boolean().default(true),
+  /** false hides the "was this helpful?" row. */
+  feedback: z.boolean().default(true),
+  /** false hides the edit link, the last-updated line and the contributors. */
+  pageInfo: z.boolean().default(true),
+  /** false hides the copy-page and hand-to-a-model control. */
+  copyPage: z.boolean().default(true),
+  /** true removes the reading-width cap, and nothing else. */
+  fullWidth: z.boolean().default(false),
+  /**
+   * false removes the page from every duxt-owned discovery surface — the client
+   * search, its fuzzy fallback, MCP `search_docs` and the two llms indexes.
+   *
+   * It changes no URL. The page is still served, still canonical, still in the
+   * sitemap, still `noindex`-free, and `read_page` still answers for it: this
+   * makes a page un-findable, not unpublished.
+   */
+  search: z.boolean().default(true),
   /**
    * URLs this page used to be served at. The layer turns them into redirects,
    * because it is the only thing that knows which prefixes exist — the
@@ -123,13 +193,46 @@ const DRAFTS = '**/*.draft.md';
  *
  * Excluded from the page collections themselves, or every partial would also
  * be a page — in the sidebar, in the search, in llms.txt.
+ *
+ * This is the EXCLUSION glob: the whole subtree, every file in it, whatever
+ * the extension. What the partials collection reads is derived from it by
+ * `partialsInclude` — the two are not the same glob.
  */
 const PARTIALS = '**/_partials/**';
 
+/**
+ * The Markdown inside a partials subtree.
+ *
+ * One configured value answers two questions, and they do not take the same
+ * glob. A page collection has to lose the whole subtree — a screenshot beside
+ * a partial must not be read as a page either. The partials collection is
+ * itself `type: 'page'`, so it can only carry Markdown: handed the exclusion
+ * glob it swallows that same screenshot, and Content parses a PNG as a
+ * document. Conflating the two is the regression the `*.md` restriction has
+ * already been written once to prevent.
+ *
+ * Nothing is narrowed: every Markdown file the subtree holds, at whatever
+ * depth the consumer's own glob reaches, still lands in the collection. A glob
+ * that already names files (`**\/_partials/**\/*.mdc`) is left alone — it has
+ * made the restriction itself.
+ */
+function partialsInclude(partials: string) {
+  const last = partials.slice(partials.lastIndexOf('/') + 1);
+  if (last.includes('.')) return partials;
+  if (partials.endsWith('**')) return `${partials}/*.md`;
+  if (partials.endsWith('*')) return `${partials}.md`;
+  return `${partials}/**/*.md`;
+}
+
 /** The dev server shows drafts; a build does not. */
 const includeDrafts = () => process.env.NODE_ENV !== 'production';
 
-const excluded = () => (includeDrafts() ? [PARTIALS] : [PARTIALS, DRAFTS]);
+const excluded = (source: DuxtSource) => {
+  const partials = source.exclude?.partials ?? PARTIALS;
+  const drafts = source.exclude?.drafts ?? DRAFTS;
+
+  return includeDrafts() ? [partials] : [partials, drafts];
+};
 
 /**
  * Turn a compact source list into Content collections.
@@ -188,7 +291,7 @@ export function duxtSources(
       source: effective.repo
         ? {
             exclude: [
-              ...excluded(),
+              ...excluded(source),
               ...nested.map((glob) => `${effective.path}/${glob}`)
             ],
             // A tag lives outside refs/heads, so it has to be passed as a tag —
@@ -202,7 +305,7 @@ export function duxtSources(
             prefix: entry.prefix
           }
         : {
-            exclude: [...excluded(), ...nested],
+            exclude: [...excluded(source), ...nested],
             include: '**/*.md',
             cwd: join(repositoryRoot(), effective.path),
             prefix: entry.prefix
@@ -223,10 +326,13 @@ export function duxtSources(
 function partialFolders(
   resolved: DuxtResolvedSource[],
   expanded: ReturnType<typeof expandSources>
-): Map<string | undefined, { repo?: string; path: string }[]> {
+): Map<
+  string | undefined,
+  { repo?: string; path: string; partials: string }[]
+> {
   const byLocale = new Map<
     string | undefined,
-    { repo?: string; path: string }[]
+    { repo?: string; path: string; partials: string }[]
   >();
   const seen = new Set<string>();
 
@@ -238,12 +344,13 @@ function partialFolders(
     // One entry per REPOSITORY AND FOLDER, not per version: a partial is a
     // block of prose, and reading three versions of it into one collection
     // would give three blocks under one name.
-    const claim = `${key ?? ''}|${effective.repo ?? ''}:${effective.path}`;
+    const partials = source.exclude?.partials ?? PARTIALS;
+    const claim = `${key ?? ''}|${effective.repo ?? ''}:${effective.path}:${partials}`;
     if (seen.has(claim)) return;
     seen.add(claim);
 
     const list = byLocale.get(key) ?? [];
-    list.push({ repo: effective.repo, path: effective.path });
+    list.push({ repo: effective.repo, path: effective.path, partials });
     byLocale.set(key, list);
   });
 
@@ -264,15 +371,17 @@ function partialFolders(
  * Two sources defining the same name is a collision the build reports rather
  * than resolves; see `modules/validate.ts`.
  */
-function definePartials(folders: { repo?: string; path: string }[]) {
+function definePartials(
+  folders: { repo?: string; path: string; partials: string }[]
+) {
   const entries = folders.map((folder) =>
     folder.repo
       ? {
           repository: repoUrl(folder.repo),
-          include: `${folder.path}/_partials/**/*.md`
+          include: `${folder.path}/${partialsInclude(folder.partials)}`
         }
       : {
-          include: '_partials/**/*.md',
+          include: partialsInclude(folder.partials),
           cwd: join(repositoryRoot(), folder.path)
         }
   ) as NonNullable<Parameters<typeof defineCollection>[0]['source']>[];

package/tfplugindocs.ts

@@ -0,0 +1,158 @@
+import type { ContentNavigationItem } from '@nuxt/content';
+
+/** The order Terraform Registry gives the generated provider categories. */
+const CATEGORY_ORDER = [
+  'index',
+  'guides',
+  'resources',
+  'data-sources',
+  'ephemeral-resources',
+  'list-resources',
+  'actions',
+  'state-stores',
+  'functions'
+] as const;
+
+type TfplugindocsPage = Record<string, unknown>;
+type NavigationItem = ContentNavigationItem & { subcategory?: string };
+
+/**
+ * Bring tfplugindocs' Registry-oriented metadata into the ordinary page shape.
+ *
+ * The files remain ordinary Markdown pages: this only replaces the title a
+ * sidebar reads and carries the generator's directory category forward. The
+ * body is deliberately untouched, so a provider still renders on the Registry.
+ */
+export function normaliseTfplugindocsPage(
+  page: TfplugindocsPage,
+  file: string
+) {
+  const category = categoryForFile(file);
+  const title =
+    headingTitle(page.title) ?? pageTitle(page.page_title) ?? fileName(file);
+
+  page.title = title;
+  page.category = category;
+}
+
+function headingTitle(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !value.trim()) return undefined;
+
+  return value.replace(/\s+\([^)]*\)\s*$/, '').trim();
+}
+
+function pageTitle(value: unknown): string | undefined {
+  if (typeof value !== 'string' || !value.trim()) return undefined;
+
+  return (
+    value
+      // tfplugindocs writes `<name> <kind> - <provider>`; providers may call
+      // themselves `linear` as well as `terraform-provider-linear`.
+      .replace(/\s+-\s+[^\s]+\s*$/, '')
+      .replace(
+        /\s+(?:resource|data source|ephemeral resource|list resource|action|state store|function|provider)\s*$/i,
+        ''
+      )
+      .trim()
+  );
+}
+
+function fileName(file: string) {
+  return (
+    file
+      .split('/')
+      .at(-1)
+      ?.replace(/\.[^.]+$/, '') || 'index'
+  );
+}
+
+function categoryForFile(file: string) {
+  const parts = file.split('/').filter(Boolean);
+  const name = fileName(file);
+  return name === 'index' ? 'index' : (parts.at(-2) ?? 'index');
+}
+
+/**
+ * Shape a tfplugindocs collection's ordinary Content tree for provider docs.
+ *
+ * Content already makes the directory categories. Only their Registry order
+ * and tfplugindocs' frontmatter-only `subcategory` need layer work. Groups
+ * receive synthetic paths solely as stable Vue keys; they never become routes.
+ */
+export function tfplugindocsNavigation(
+  tree: ContentNavigationItem[],
+  prefix: string
+): ContentNavigationItem[] {
+  return orderCategories(tree, prefix).map(groupSubcategories);
+}
+
+function orderCategories(
+  items: ContentNavigationItem[],
+  prefix: string
+): ContentNavigationItem[] {
+  return [...items]
+    .sort((left, right) => {
+      const difference =
+        categoryRank(left.path, prefix) - categoryRank(right.path, prefix);
+      return difference || left.title.localeCompare(right.title);
+    })
+    .map((item) => ({
+      ...item,
+      ...(item.children?.length
+        ? { children: orderCategories(item.children, prefix) }
+        : {})
+    }));
+}
+
+function categoryRank(path: string | undefined, prefix: string) {
+  if (path === prefix) return 0;
+
+  const category = path?.slice(prefix.length).split('/').filter(Boolean)[0];
+  const rank = CATEGORY_ORDER.indexOf(
+    category as (typeof CATEGORY_ORDER)[number]
+  );
+  return rank === -1 ? CATEGORY_ORDER.length + 1 : rank + 1;
+}
+
+function groupSubcategories(
+  item: ContentNavigationItem
+): ContentNavigationItem {
+  const children = item.children?.map(groupSubcategories);
+  if (!children?.length) return item;
+
+  const pages = children as NavigationItem[];
+  const grouped = new Map<string, NavigationItem[]>();
+  const direct: NavigationItem[] = [];
+
+  for (const child of pages) {
+    if (!child.subcategory) {
+      direct.push(child);
+      continue;
+    }
+
+    const group = grouped.get(child.subcategory) ?? [];
+    group.push(child);
+    grouped.set(child.subcategory, group);
+  }
+
+  if (!grouped.size) return { ...item, children };
+
+  const groups = [...grouped.entries()]
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([title, members], index) => ({
+      title,
+      path: `${item.path ?? ''}/__duxt-subcategory-${index}`,
+      page: false as const,
+      children: [...members].sort((left, right) =>
+        left.title.localeCompare(right.title)
+      )
+    }));
+
+  return {
+    ...item,
+    children: [
+      ...direct.sort((left, right) => left.title.localeCompare(right.title)),
+      ...groups
+    ]
+  };
+}