@writedocs/generator 0.4.7 → 0.4.9

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