@waveso/docs 0.5.0 → 0.7.0

package/dist/types.d.ts

@@ -15,6 +15,21 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  * `Property 'audience' does not exist on type 'DocFrontmatter'` at every read
  * site, because the inference then collapses to this default.
  */
+/**
+ * One call to action in a page's hero.
+ *
+ * `variant` is optional because the shape every landing page has is
+ * primary-then-secondary: the first action is the primary unless it says
+ * otherwise.
+ */
+interface DocAction {
+  /** Visible text. */
+  label: string;
+  /** Where it goes. Internal hrefs route; external ones open in a new tab. */
+  href: string;
+  /** Overrides the position-derived default. */
+  variant?: 'primary' | 'secondary' | undefined;
+}
 interface DocFrontmatter {
   /** Page title. Used for `<h1>` fallbacks, `<title>`, and search. */
   title: string;
@@ -44,6 +59,21 @@ interface DocFrontmatter {
    * Lower sorts first; pages without an order sort last, alphabetically.
    */
   order?: number | undefined;
+  /**
+   * Calls to action, and the opt-in for the page's hero.
+   *
+   * Declaring them turns {@link DocFrontmatter.title} and
+   * {@link DocFrontmatter.description} into a page header with these links
+   * under it, and stops `render` prepending its own `<h1>` — the hero renders
+   * the heading, because the tagline and the actions have to sit beneath it.
+   *
+   * Leave it off and the page is exactly what it was: the description stays a
+   * `<meta>` tag and the title is the first thing in the prose. That is the
+   * whole difference between documentation that is the entire site and
+   * documentation mounted inside an application that already has a landing
+   * page — one field, in the file that wants it.
+   */
+  actions?: DocAction[] | undefined;
 }
 /**
  * A single documentation page discovered on disk.
@@ -244,11 +274,24 @@ interface DocLinkContext {
   /** The source path, e.g. `'api/auth.md'`. For error messages. */
   relativePath: string;
 }
+/**
+ * What a link problem should do to a build.
+ *
+ * The three Docusaurus settled on, and for the same reason: the tool cannot
+ * know how much a given site cares, and guessing produces either a build that
+ * fails on someone's legitimate URL or one that ships a dead link quietly.
+ *
+ * `'warn'` writes to `console.warn` and continues, which on a docs site is a
+ * line in a build log — useful during a migration, not a substitute for
+ * `'throw'`.
+ */
+type DocsLinkSeverity = 'throw' | 'warn' | 'ignore';
 /**
  * Resolve an internal markdown link target to a route.
  *
  * Called for every relative link found in the source. Returning `undefined`
- * signals "not a documentation page", which — with `assertLinks` on — fails
+ * signals "not a documentation page", which — under the default
+ * `onBrokenLinks: 'throw'` — fails
  * the build rather than shipping a 404 that was valid on GitHub.
  */
 type LinkResolver = (
@@ -321,10 +364,61 @@ interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    */
   includeDrafts?: boolean | undefined;
   /**
-   * Fail the build when an internal link resolves to a page that does not
-   * exist. Defaults to `true`; there is no good reason to turn it off.
+   * What to do about an internal link that resolves to no published page.
+   * Defaults to `'throw'`.
+   *
+   * A link that 404s was valid in the editor and on GitHub, so it is the kind
+   * of mistake nobody finds by reading. Throwing is the default for that
+   * reason, and there is rarely a good reason to lower it — `'warn'` exists
+   * for a migration where the corpus is knowingly incomplete for a while.
+   *
+   * The error names the file and the line, and offers the closest published
+   * route when the link looks like a typo of one.
+   */
+  onBrokenLinks?: DocsLinkSeverity | undefined;
+  /**
+   * What to do about a `#fragment` that no heading on the target page owns.
+   * Defaults to `'throw'`.
+   *
+   * ⚠️ THE MORE COMMON OF THE TWO LINK FAILURES, AND IT WENT UNCHECKED. A route
+   * was verified and its fragment discarded, so `[setup](./install.md#setup)`
+   * built green with no `#setup` anywhere on the page. Headings get renamed
+   * constantly and nothing renames the links into them, which is exactly why it
+   * is worth checking and exactly why it breaks.
+   *
+   * Checked against every `id` in the rendered page rather than against the
+   * table of contents, which captures `h2`–`h3` only — so a link to an `h4` is
+   * fine, and so is one to an id a `rehypePlugins` entry put on something that
+   * is not a heading.
+   *
+   * Lower it to `'warn'` if a plugin of yours adds ids this package cannot see
+   * at render time.
+   */
+  onBrokenAnchors?: DocsLinkSeverity | undefined;
+  /**
+   * Route prefixes that belong to your application, not to the documentation.
+   *
+   * ⚠️ ONLY MEANINGFUL AT A ROOT MOUNT, WHICH IS ALSO THE ONLY PLACE IT IS
+   * NEEDED. Under `basePath: '/docs'` an absolute link either carries the
+   * prefix — so it is documentation and is checked — or it does not, and this
+   * package leaves it alone. Under `basePath: '/'` there is no prefix to test
+   * against: `/setup` and `/login` look identical, and both are checked against
+   * the published pages.
+   *
+   * That is the right default, because a root mount is what you choose when the
+   * origin serves documentation and nothing else — `docs.example.com` — and
+   * there an unknown absolute link is always a typo. If the origin *does* serve
+   * something else, name what is yours:
+   *
+   * ```ts
+   * externalRoutes: ['/login', '/dashboard', '/api/']
+   * ```
+   *
+   * A link is skipped when it equals one of these or begins with one followed
+   * by `/`. It is a statement about your application, so nothing here can infer
+   * it and nothing tries.
    */
-  assertLinks?: boolean | undefined;
+  externalRoutes?: readonly string[] | undefined;
   /**
    * Validates every page's frontmatter. Defaults to `docFrontmatterSchema`
    * from `@waveso/docs/frontmatter`.
@@ -375,7 +469,9 @@ interface ResolvedDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatte
   contentDir: string;
   basePath: string;
   includeDrafts: boolean;
-  assertLinks: boolean;
+  onBrokenLinks: DocsLinkSeverity;
+  onBrokenAnchors: DocsLinkSeverity;
+  externalRoutes: readonly string[];
   /**
    * As supplied. `resolveDocsConfig` omits the key rather than setting it to
    * `undefined` when the built-in `docFrontmatterSchema` applies, so the
@@ -384,4 +480,4 @@ interface ResolvedDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatte
   frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter> | undefined;
 }
 //#endregion
-export { DocFile, DocFrontmatter, DocLinkContext, DocNavGroup, DocNavLink, DocNavNode, DocNavPage, DocNavSeparator, DocsConfig, DocsMeta, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig, SearchRecord, TocEntry };
+export { DocAction, DocFile, DocFrontmatter, DocLinkContext, DocNavGroup, DocNavLink, DocNavNode, DocNavPage, DocNavSeparator, DocsConfig, DocsLinkSeverity, DocsMeta, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig, SearchRecord, TocEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [
@@ -68,6 +68,10 @@
       "types": "./dist/react/callout.d.ts",
       "default": "./dist/react/callout.js"
     },
+    "./react/hero": {
+      "types": "./dist/react/hero.d.ts",
+      "default": "./dist/react/hero.js"
+    },
     "./react/doc-content": {
       "types": "./dist/react/doc-content.d.ts",
       "default": "./dist/react/doc-content.js"
@@ -76,6 +80,10 @@
       "types": "./dist/react/markdown-components.d.ts",
       "default": "./dist/react/markdown-components.js"
     },
+    "./react/next-link": {
+      "types": "./dist/react/next-link.d.ts",
+      "default": "./dist/react/next-link.js"
+    },
     "./react/next-search": {
       "types": "./dist/react/next-search.d.ts",
       "default": "./dist/react/next-search.js"
@@ -196,7 +204,6 @@
     "test:smoke": "node smoke/check.ts",
     "size": "node scripts/size.ts",
     "build:site": "next build site",
-    "dev:site": "next dev site",
-    "shoot": "node scripts/shoot.ts"
+    "dev:site": "next dev site"
   }
 }