@writedocs/generator 0.4.8 → 0.4.10

package/src/components/Update.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <Update> - one changelog entry: `label` (usually a date or
 // version) in a left column that sticks while its content scrolls, with
 // `description` and `tags` under it. The label is a linkable anchor, deduped
@@ -25,7 +26,7 @@ function slugify(value: string): string {
 }
 const id = _titleId ?? slugify(label);
 ---
-<section class="wd-update" data-update-tags={JSON.stringify(tags)}>
+<section class:list={["wd-update", extraClasses(Astro.props)]} data-update-tags={JSON.stringify(tags)}>
   <div class="wd-update-meta">
     <div class="wd-update-label" id={id}>
       <a href={`#${id}`}>{label}</a>

package/src/components/Video.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Renders either a native <video> or an <iframe> embed from the same
 // `src` prop, auto-detected rather than requiring the author to pick -
 // `src="media/clip.mp4"` (a direct video file, local or remote) gets a
@@ -57,7 +58,7 @@ const sizeStyle = width ? `--wd-video-size:${width}` : undefined;
 const effectiveMuted = muted || autoplay;
 ---
 
-<figure class:list={["wd-video-figure", caption && "wd-video-figure-framed"]} style={sizeStyle}>
+<figure class:list={["wd-video-figure", caption && "wd-video-figure-framed", extraClasses(Astro.props)]} style={sizeStyle}>
   {
     isFile ? (
       <video

package/src/components/View.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 // Mintlify's <View title="..." icon="..."> - content for one of several
 // alternatives (a language, a framework) on the same page. Every distinct
 // `title` on the page becomes an option in one switcher, placed under the
@@ -16,7 +17,7 @@ interface Props {
 }
 const { title, icon } = Astro.props as Props;
 ---
-<div class="wd-view" data-view-title={title}>
+<div class:list={["wd-view", extraClasses(Astro.props)]} data-view-title={title}>
   {icon && <span class="wd-view-icon-src" hidden><AppIcon icon={icon} class="wd-view-icon" /></span>}
   <slot />
 </div>

package/src/components/Warning.astro

@@ -9,4 +9,4 @@ interface Props {
 }
 const { title, _titleId } = Astro.props as Props;
 ---
-<Callout type="warning" title={title} _titleId={_titleId}><slot /></Callout>
+<Callout type="warning" title={title} _titleId={_titleId} class={Astro.props.class} className={Astro.props.className}><slot /></Callout>

package/src/components/class-names.ts

@@ -0,0 +1,8 @@
+// Every built-in component takes extra classes for its root element - as
+// `className` (how MDX, and Mintlify content, passes it) or `class` (Astro's
+// own spelling). Components add extraClasses(Astro.props) to their root
+// element's class:list; with neither set it adds nothing, so the rendered
+// markup is unchanged.
+export function extraClasses(props: Record<string, unknown>): string[] {
+  return [props.class, props.className].filter((c): c is string => typeof c === 'string' && c.trim() !== '');
+}

package/src/components/index.ts

@@ -50,6 +50,8 @@ export { default as Check } from './Check.astro';
 export { default as ParamField } from './ParamField.astro';
 export { default as ResponseField } from './ResponseField.astro';
 export { default as Columns } from './Columns.astro';
+export { default as Column } from './Column.astro';
+export { default as CodeBlock } from './CodeBlock.astro';
 export { default as Tooltip } from './Tooltip.astro';
 export { default as Update } from './Update.astro';
 export { default as Tile } from './Tile.astro';

package/src/content.config.ts

@@ -1,11 +1,11 @@
 import { defineCollection } from 'astro:content';
 import { glob } from 'astro/loaders';
 import type { Loader } from 'astro/loaders';
-import { z } from 'astro/zod';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { seoFieldsSchema, findAllPages } from './lib/config';
+import { pageFrontmatterSchema, findAllPages } from './lib/config';
+import { titleFromPath } from './lib/pages.js';
 import { writedocsTempDir } from './lib/writedocs-temp-dir.js';
 
 const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
@@ -32,131 +32,11 @@ const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
 const generatedDocsDir = path.join(writedocsTempDir(contentDir), 'generated-docs');
 const generatedDocsBase = pathToFileURL(generatedDocsDir + path.sep);
 
-const MINTLIFY_MODE_ALIASES: Record<string, string> = { center: 'frame', assistant: 'default' };
-
-const docsSchema = z.object({
-  title: z.string(),
-  description: z.string().optional(),
-  // Overrides the URL this page is served at, independent of where the
-  // file actually lives - writedocs.json's `pages` arrays always keep
-  // referencing the file's own path regardless. This is Astro's own
-  // glob()-loader convention (a `slug` frontmatter field becomes
-  // `entry.id` verbatim - see generateIdDefault in
-  // astro/dist/content/loaders/glob.js), not writedocs-specific
-  // behavior; declaring it here just brings it into the schema (and
-  // its docs) rather than leaving it an undocumented Astro feature.
-  // See fileIdForEntry() in lib/config.ts for how routes/links still
-  // resolve a page by its file id once this diverges from `entry.id`.
-  // Leading/trailing slashes are fine either way ("/", "/guides/x",
-  // "guides/x" and "guides/x/" all mean the same thing) - see
-  // normalizeEntryId() in lib/config.ts, which is what actually
-  // strips them before this value is ever used as a route or href.
-  slug: z.string().optional(),
-  // Marks this page as an OpenAPI operation reference: "METHOD /path"
-  // matching an operation in the owning group's OpenAPI spec, e.g.
-  // "GET /pets/{petId}" - [...slug].astro renders <ApiPlayground /> for
-  // any page with this field set, below the page's own MDX body (if
-  // any). Sites don't write this by hand for most pages; it's either
-  // set on a generated stub in the `generatedDocs` collection below (see
-  // generate-api-pages.js) or hand-authored to "eject" one specific
-  // operation into a real file (in `docs`) with custom prose - either
-  // way, the value is always exactly the same "METHOD /path" key
-  // generate-api-pages.js uses to look up the operation's full resolved
-  // schema/examples at render time.
-  openapi: z.string().optional(),
-  // Controls how much of the site's own chrome (topbar, sidebar, table of
-  // contents) wraps this page - see BaseLayout.astro/[...slug].astro for
-  // what each value actually removes:
-  //   default - the normal three-column reading layout (all chrome).
-  //   wide    - drops the table of contents; the article itself also
-  //             renders wider, for content that wants the extra room
-  //             (wide tables, side-by-side images).
-  //   frame   - drops the sidebar and table of contents, but keeps the
-  //             topbar and the article's own normal presentation
-  //             ("frame" as in: still inside the site's outer frame).
-  //   custom  - drops the sidebar and table of contents, the
-  //             auto-rendered <h1>, and prev/next nav, and skips the
-  //             article's own prose width/padding too - a blank canvas
-  //             for a hand-built landing/home page made entirely of
-  //             components - but keeps the topbar, so the page still
-  //             has site branding/nav/search/theme-toggle available.
-  //   blank   - everything 'custom' drops, plus the topbar too: no site
-  //             chrome at all, just <slot />. For a page that wants to
-  //             look nothing like the rest of the site (an auth screen,
-  //             a print-style page).
-  //
-  // Two Mintlify values are accepted so a migrated page doesn't fail the
-  // build (see MINTLIFY_MODE_ALIASES below): `center` is the same layout
-  // as our `frame`, and `assistant` (a full-page Mintlify AI chat, which
-  // writedocs doesn't have) falls back to `default`. Mintlify's own
-  // `frame` means something else (a canvas that keeps the sidebar) - it's
-  // left as our `frame`; see docs/dev/docs/mintlify-compat.mdx.
-  mode: z
-    .preprocess(
-      (value) => (typeof value === 'string' && value in MINTLIFY_MODE_ALIASES ? MINTLIFY_MODE_ALIASES[value] : value),
-      z.enum(['default', 'wide', 'frame', 'custom', 'blank']),
-    )
-    .default('default'),
-  // Per-page meta tag overrides - same shape as writedocs.json's top-level
-  // `seo` (see seoFieldsSchema in lib/config.ts, the single source of
-  // truth for this shape). A page only needs to set the specific fields
-  // it wants to override; mergeSeo() falls back to the site-wide default
-  // for anything left unset. See BaseLayout.astro for where this and the
-  // site-wide seo actually get merged and rendered.
-  seo: seoFieldsSchema.optional(),
-  // Mintlify's spelling of `seo.noindex` - a top-level `noindex: true`.
-  // Folded into `seo` by the transform below, so everything downstream
-  // (the robots meta tag, sitemap.xml, llms.txt) keeps reading
-  // `seo.noindex` only.
-  noindex: z.boolean().optional(),
-  // Mintlify's short navigation label - used for the sidebar and the
-  // topbar dropdown menus in place of `title` ([...slug].astro's
-  // navTitleForSlug). The page's own <h1> and prev/next links keep `title`.
-  sidebarTitle: z.string().optional(),
-  // Mintlify's spellings of `seo.keywords`, `seo.ogImage`, `seo.ogType`
-  // and `seo.twitterCard`, folded into `seo` below like `noindex`.
-  keywords: z.array(z.string()).optional(),
-  'og:image': z.string().optional(),
-  'og:type': z.string().optional(),
-  'twitter:card': z.enum(['summary', 'summary_large_image']).optional(),
-  // Mintlify's sidebar/page-chrome fields - see NavTree.astro and
-  // [...slug].astro for where each is used:
-  //   icon                 - shown before the page's label in the sidebar.
-  //   tag                  - a short label after it (e.g. "NEW").
-  //   deprecated           - a "Deprecated" label in the sidebar and next
-  //                          to the page's <h1>.
-  //   hidden               - left out of the sidebar, dropdowns and
-  //                          prev/next, but still built and reachable by
-  //                          URL. Also noindexed, as on Mintlify.
-  //   url                  - an external link: the page's sidebar entry
-  //                          links straight to it, and the page's own URL
-  //                          redirects there.
-  //   hideFooterPagination - no prev/next links on this page.
-  //   hideApiMarker        - no HTTP method badge on this page's sidebar
-  //                          entry.
-  icon: z.string().optional(),
-  tag: z.string().optional(),
-  deprecated: z.boolean().optional(),
-  hidden: z.boolean().optional(),
-  url: z.string().optional(),
-  hideFooterPagination: z.boolean().optional(),
-  hideApiMarker: z.boolean().optional(),
-}).transform(
-  ({ noindex, keywords, 'og:image': ogImage, 'og:type': ogType, 'twitter:card': twitterCard, ...data }) => {
-    // Top-level Mintlify keys fill in `seo` only where the page's own `seo`
-    // doesn't already set that field - an explicit `seo` value always wins.
-    // A `hidden` page is noindexed unless it says otherwise.
-    const fromMintlify = { noindex: noindex ?? (data.hidden ? true : undefined), keywords, ogImage, ogType, twitterCard };
-    const seo = { ...data.seo };
-    let changed = false;
-    for (const [key, value] of Object.entries(fromMintlify)) {
-      if (value === undefined || seo[key as keyof typeof seo] !== undefined) continue;
-      (seo as Record<string, unknown>)[key] = value;
-      changed = true;
-    }
-    return changed ? { ...data, seo } : data;
-  },
-);
+// Page frontmatter - defined in lib/config-schema.ts as
+// pageFrontmatterSchema, next to writedocs.json's own schema, so
+// `writedocs validate` checks every page against exactly the schema the
+// build uses (that file compiles to the plain JS validate loads).
+const docsSchema = pageFrontmatterSchema;
 
 /** Wraps another loader so it's skipped entirely - no filesystem scan, no
  *  "directory doesn't exist"/"no files found" warning - when its own base
@@ -172,11 +52,31 @@ function skipIfMissing(inner: Loader): Loader {
     name: inner.name,
     load: async (context) => {
       if (!fs.existsSync(generatedDocsBase)) return;
-      return inner.load(context);
+      return inner.load(withTitleFallback(context));
     },
   };
 }
 
+// A page with no `title` in its frontmatter gets one from its file name,
+// before the schema (which requires `title`) sees it - Mintlify's rule, so
+// a migrated page that relied on it builds with the same title. See
+// titleFromPath() in lib/pages.js; `writedocs validate` applies the same
+// default (lib/content-check.js).
+type LoaderContext = Parameters<Loader['load']>[0];
+function withTitleFallback(context: LoaderContext): LoaderContext {
+  return {
+    ...context,
+    parseData: (props) =>
+      context.parseData({
+        ...props,
+        data:
+          typeof props.data?.title === 'string'
+            ? props.data
+            : { ...props.data, title: titleFromPath(props.filePath ?? props.id) },
+      }),
+  };
+}
+
 const generatedDocs = defineCollection({
   loader: skipIfMissing(glob({ pattern: '**/*.{md,mdx}', base: generatedDocsBase })),
   schema: docsSchema,
@@ -256,7 +156,7 @@ function livePages(dir: string, base: URL): Loader {
           for (const id of store.keys()) store.delete(id);
           return;
         }
-        await glob({ pattern: files, base }).load({ ...context, watcher: undefined });
+        await glob({ pattern: files, base }).load({ ...withTitleFallback(context), watcher: undefined });
       }
 
       await resync();

package/src/lib/config-schema.js

@@ -259,6 +259,125 @@ function mergeSeo(site, page) {
     noindex: page.noindex ?? site.noindex
   };
 }
+const MINTLIFY_MODE_ALIASES = { center: "frame", assistant: "default" };
+const pageFrontmatterSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  // Overrides the URL this page is served at, independent of where the
+  // file actually lives - writedocs.json's `pages` arrays always keep
+  // referencing the file's own path regardless. This is Astro's own
+  // glob()-loader convention (a `slug` frontmatter field becomes
+  // `entry.id` verbatim - see generateIdDefault in
+  // astro/dist/content/loaders/glob.js), not writedocs-specific
+  // behavior; declaring it here just brings it into the schema (and
+  // its docs) rather than leaving it an undocumented Astro feature.
+  // See fileIdForEntry() in lib/config.ts for how routes/links still
+  // resolve a page by its file id once this diverges from `entry.id`.
+  // Leading/trailing slashes are fine either way ("/", "/guides/x",
+  // "guides/x" and "guides/x/" all mean the same thing) - see
+  // normalizeEntryId() in lib/config.ts, which is what actually
+  // strips them before this value is ever used as a route or href.
+  slug: z.string().optional(),
+  // Marks this page as an OpenAPI operation reference: "METHOD /path"
+  // matching an operation in the owning group's OpenAPI spec, e.g.
+  // "GET /pets/{petId}" - [...slug].astro renders <ApiPlayground /> for
+  // any page with this field set, below the page's own MDX body (if
+  // any). Sites don't write this by hand for most pages; it's either
+  // set on a generated stub in the `generatedDocs` collection below (see
+  // generate-api-pages.js) or hand-authored to "eject" one specific
+  // operation into a real file (in `docs`) with custom prose - either
+  // way, the value is always exactly the same "METHOD /path" key
+  // generate-api-pages.js uses to look up the operation's full resolved
+  // schema/examples at render time.
+  openapi: z.string().optional(),
+  // Controls how much of the site's own chrome (topbar, sidebar, table of
+  // contents) wraps this page - see BaseLayout.astro/[...slug].astro for
+  // what each value actually removes:
+  //   default - the normal three-column reading layout (all chrome).
+  //   wide    - drops the table of contents; the article itself also
+  //             renders wider, for content that wants the extra room
+  //             (wide tables, side-by-side images).
+  //   frame   - drops the sidebar and table of contents, but keeps the
+  //             topbar and the article's own normal presentation
+  //             ("frame" as in: still inside the site's outer frame).
+  //   custom  - drops the sidebar and table of contents, the
+  //             auto-rendered <h1>, and prev/next nav, and skips the
+  //             article's own prose width/padding too - a blank canvas
+  //             for a hand-built landing/home page made entirely of
+  //             components - but keeps the topbar, so the page still
+  //             has site branding/nav/search/theme-toggle available.
+  //   blank   - everything 'custom' drops, plus the topbar too: no site
+  //             chrome at all, just <slot />. For a page that wants to
+  //             look nothing like the rest of the site (an auth screen,
+  //             a print-style page).
+  //
+  // Two Mintlify values are accepted so a migrated page doesn't fail the
+  // build (see MINTLIFY_MODE_ALIASES above): `center` is the same layout
+  // as our `frame`, and `assistant` (a full-page Mintlify AI chat, which
+  // writedocs doesn't have) falls back to `default`. Mintlify's own
+  // `frame` means something else (a canvas that keeps the sidebar) - it's
+  // left as our `frame`; see docs/dev/docs/mintlify-compat.mdx.
+  mode: z.preprocess(
+    (value) => typeof value === "string" && value in MINTLIFY_MODE_ALIASES ? MINTLIFY_MODE_ALIASES[value] : value,
+    z.enum(["default", "wide", "frame", "custom", "blank"])
+  ).default("default"),
+  // Per-page meta tag overrides - same shape as writedocs.json's top-level
+  // `seo` (see seoFieldsSchema in lib/config.ts, the single source of
+  // truth for this shape). A page only needs to set the specific fields
+  // it wants to override; mergeSeo() falls back to the site-wide default
+  // for anything left unset. See BaseLayout.astro for where this and the
+  // site-wide seo actually get merged and rendered.
+  seo: seoFieldsSchema.optional(),
+  // Mintlify's spelling of `seo.noindex` - a top-level `noindex: true`.
+  // Folded into `seo` by the transform below, so everything downstream
+  // (the robots meta tag, sitemap.xml, llms.txt) keeps reading
+  // `seo.noindex` only.
+  noindex: z.boolean().optional(),
+  // Mintlify's short navigation label - used for the sidebar and the
+  // topbar dropdown menus in place of `title` ([...slug].astro's
+  // navTitleForSlug). The page's own <h1> and prev/next links keep `title`.
+  sidebarTitle: z.string().optional(),
+  // Mintlify's spellings of `seo.keywords`, `seo.ogImage`, `seo.ogType`
+  // and `seo.twitterCard`, folded into `seo` below like `noindex`.
+  keywords: z.array(z.string()).optional(),
+  "og:image": z.string().optional(),
+  "og:type": z.string().optional(),
+  "twitter:card": z.enum(["summary", "summary_large_image"]).optional(),
+  // Mintlify's sidebar/page-chrome fields - see NavTree.astro and
+  // [...slug].astro for where each is used:
+  //   icon                 - shown before the page's label in the sidebar.
+  //   tag                  - a short label after it (e.g. "NEW").
+  //   deprecated           - a "Deprecated" label in the sidebar and next
+  //                          to the page's <h1>.
+  //   hidden               - left out of the sidebar, dropdowns and
+  //                          prev/next, but still built and reachable by
+  //                          URL. Also noindexed, as on Mintlify.
+  //   url                  - an external link: the page's sidebar entry
+  //                          links straight to it, and the page's own URL
+  //                          redirects there.
+  //   hideFooterPagination - no prev/next links on this page.
+  //   hideApiMarker        - no HTTP method badge on this page's sidebar
+  //                          entry.
+  icon: z.string().optional(),
+  tag: z.string().optional(),
+  deprecated: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  url: z.string().optional(),
+  hideFooterPagination: z.boolean().optional(),
+  hideApiMarker: z.boolean().optional()
+}).transform(
+  ({ noindex, keywords, "og:image": ogImage, "og:type": ogType, "twitter:card": twitterCard, ...data }) => {
+    const fromMintlify = { noindex: noindex ?? (data.hidden ? true : void 0), keywords, ogImage, ogType, twitterCard };
+    const seo = { ...data.seo };
+    let changed = false;
+    for (const [key, value] of Object.entries(fromMintlify)) {
+      if (value === void 0 || seo[key] !== void 0) continue;
+      seo[key] = value;
+      changed = true;
+    }
+    return changed ? { ...data, seo } : data;
+  }
+);
 const apiSchema = z.object({
   // Whether the Try-it modal's Send button routes its request through
   // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
@@ -505,6 +624,9 @@ function desembrulharUnioes(issues, prefixo = []) {
   }
   return saida;
 }
+function createJsonLocator(rawText) {
+  return criarLocalizador(rawText);
+}
 function criarLocalizador(rawText) {
   let arvore;
   try {
@@ -700,10 +822,12 @@ function validateDocsConfig(rawText) {
 }
 export {
   ROOT_ALLOWED_EXTRA_KEYS,
+  createJsonLocator,
   docsConfigSchema,
   formatValidationIssues,
   formatValidationIssuesDetailed,
   mergeSeo,
+  pageFrontmatterSchema,
   seoFieldsSchema,
   unknownRootKeyIssues,
   validateDocsConfig