@heyo-sh/create-heyo-docs 0.2.3 → 0.4.0

package/templates/next/app/components/docs-app.tsx

@@ -18,7 +18,6 @@ import {
 } from "react";
 
 import { docsConfig, openApiEndpoints, pages } from "../_heyo-docs/content";
-import config from "../../heyo-docs.config";
 import { iconSet } from "../heyo-docs-icons";
 import { useTheme } from "./theme-provider";
 
@@ -119,7 +118,7 @@ export function NextDocsApp({
   return (
     <NextNavigationContext.Provider value={navigate}>
       <DocsApp
-        config={{ ...docsConfig, navigation: config.navigation }}
+        config={docsConfig}
         iconSet={iconSet}
         isDark={mounted ? resolvedTheme === "dark" : undefined}
         link={NextDocsLink}

package/templates/next/app/heyo-docs-internal/ai-chat/route.ts

@@ -0,0 +1,15 @@
+import { createAiChatResponse } from "@heyo-sh/heyo-docs/ai";
+
+import config from "../../../heyo-docs.config";
+import { docsPages, markdownPages } from "../../_heyo-docs/server";
+
+export const runtime = "nodejs";
+
+export async function POST(request: Request) {
+  return createAiChatResponse(request, {
+    ai: config.ai,
+    markdownPages,
+    pages: docsPages,
+    title: config.title,
+  });
+}

package/templates/next/app/layout.tsx

@@ -1,8 +1,68 @@
 import type { Metadata } from "next";
 import type { ReactNode } from "react";
+import { adobeAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/adobe";
+import { amplitudeAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/amplitude";
+import { clarityBootstrapScript } from "@heyo-sh/heyo-docs/integrations/analytics/clarity";
+import { clearbitAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/clearbit";
+import { fathomAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/fathom";
+import {
+  googleAnalyticsBootstrapScript,
+  googleAnalyticsScript,
+} from "@heyo-sh/heyo-docs/integrations/analytics/google-analytics";
+import {
+  googleTagManagerBootstrapScript,
+  googleTagManagerNoScriptUrl,
+} from "@heyo-sh/heyo-docs/integrations/analytics/google-tag-manager";
+import { heapBootstrapScript } from "@heyo-sh/heyo-docs/integrations/analytics/heap";
+import { hotjarBootstrapScript } from "@heyo-sh/heyo-docs/integrations/analytics/hotjar";
+import {
+  logRocketBootstrapScript,
+  logRocketScript,
+} from "@heyo-sh/heyo-docs/integrations/analytics/logrocket";
+import {
+  mixpanelBootstrapScript,
+  mixpanelScript,
+} from "@heyo-sh/heyo-docs/integrations/analytics/mixpanel";
+import {
+  openpanelBootstrapScript,
+  openpanelScript,
+} from "@heyo-sh/heyo-docs/integrations/analytics/openpanel";
+import { openReplayBootstrapScript } from "@heyo-sh/heyo-docs/integrations/analytics/openreplay";
+import { osanoConsentScript } from "@heyo-sh/heyo-docs/integrations/consent/osano";
+import {
+  transcendConsentScript,
+  transcendGoogleConsentModeDefaultsScript,
+} from "@heyo-sh/heyo-docs/integrations/consent/transcend";
+import { pirschAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/pirsch";
+import { plausibleAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/plausible";
+import {
+  posthogApiHost,
+  posthogBootstrapScript,
+  posthogScript,
+} from "@heyo-sh/heyo-docs/integrations/analytics/posthog";
+import { rybbitAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/rybbit";
+import {
+  swetrixBootstrapScript,
+  swetrixScript,
+} from "@heyo-sh/heyo-docs/integrations/analytics/swetrix";
+import { chaskiqBootstrapScript } from "@heyo-sh/heyo-docs/integrations/support/chaskiq";
+import { chatwootBootstrapScript } from "@heyo-sh/heyo-docs/integrations/support/chatwoot";
+import {
+  frontChatBootstrapScript,
+  frontChatScript,
+} from "@heyo-sh/heyo-docs/integrations/support/front";
+import { intercomBootstrapScript } from "@heyo-sh/heyo-docs/integrations/support/intercom";
+import { papercupsBootstrapScript } from "@heyo-sh/heyo-docs/integrations/support/papercups";
+import { typebotBootstrapScript } from "@heyo-sh/heyo-docs/integrations/support/typebot";
+import { umamiAnalyticsScript } from "@heyo-sh/heyo-docs/integrations/analytics/umami";
+import {
+  zammadBootstrapScript,
+  zammadChatScript,
+} from "@heyo-sh/heyo-docs/integrations/support/zammad";
 
 import config from "../heyo-docs.config";
 import "./app.css";
+import "./_heyo-docs/theme.css";
 import { ThemeProvider } from "./components/theme-provider";
 import { getThemeScript, THEME_STORAGE_KEY } from "./lib/theme";
 
@@ -42,17 +102,305 @@ export const metadata: Metadata = {
   },
 };
 
+const osano = config.integrations.consent.osano
+  ? osanoConsentScript(config.integrations.consent.osano)
+  : undefined;
+const transcend = config.integrations.consent.transcend
+  ? transcendConsentScript(config.integrations.consent.transcend)
+  : undefined;
+const transcendGoogleConsentDefaults =
+  transcend &&
+  (config.integrations.analytics.ga4 || config.integrations.analytics.gtm)
+    ? transcendGoogleConsentModeDefaultsScript()
+    : undefined;
+const adobe = config.integrations.analytics.adobe
+  ? adobeAnalyticsScript(config.integrations.analytics.adobe)
+  : undefined;
+const amplitude = config.integrations.analytics.amplitude
+  ? amplitudeAnalyticsScript(config.integrations.analytics.amplitude)
+  : undefined;
+const clarity = config.integrations.analytics.clarity
+  ? clarityBootstrapScript()
+  : undefined;
+const clearbit = config.integrations.analytics.clearbit
+  ? clearbitAnalyticsScript(config.integrations.analytics.clearbit)
+  : undefined;
+const fathom = config.integrations.analytics.fathom
+  ? fathomAnalyticsScript(config.integrations.analytics.fathom)
+  : undefined;
+const googleAnalytics = config.integrations.analytics.ga4
+  ? googleAnalyticsScript(config.integrations.analytics.ga4)
+  : undefined;
+const googleAnalyticsBootstrap = googleAnalytics
+  ? googleAnalyticsBootstrapScript()
+  : undefined;
+const googleTagManager = config.integrations.analytics.gtm
+  ? googleTagManagerBootstrapScript()
+  : undefined;
+const googleTagManagerNoScript = config.integrations.analytics.gtm
+  ? googleTagManagerNoScriptUrl(config.integrations.analytics.gtm)
+  : undefined;
+const heap = config.integrations.analytics.heap
+  ? heapBootstrapScript()
+  : undefined;
+const hotjar = config.integrations.analytics.hotjar
+  ? hotjarBootstrapScript()
+  : undefined;
+const logRocket = config.integrations.analytics.logrocket
+  ? logRocketScript()
+  : undefined;
+const logRocketBootstrap = logRocket ? logRocketBootstrapScript() : undefined;
+const mixpanel = config.integrations.analytics.mixpanel
+  ? mixpanelScript()
+  : undefined;
+const mixpanelBootstrap = mixpanel ? mixpanelBootstrapScript() : undefined;
+const openpanel = config.integrations.analytics.openpanel
+  ? openpanelScript()
+  : undefined;
+const openpanelBootstrap = openpanel ? openpanelBootstrapScript() : undefined;
+const openReplay = config.integrations.analytics.openreplay
+  ? openReplayBootstrapScript()
+  : undefined;
+const pirsch = config.integrations.analytics.pirsch
+  ? pirschAnalyticsScript(config.integrations.analytics.pirsch)
+  : undefined;
+const plausible = config.integrations.analytics.plausible
+  ? plausibleAnalyticsScript(config.integrations.analytics.plausible)
+  : undefined;
+const posthog = config.integrations.analytics.posthog
+  ? posthogScript(config.integrations.analytics.posthog)
+  : undefined;
+const posthogBootstrap = posthog ? posthogBootstrapScript() : undefined;
+const posthogHost = config.integrations.analytics.posthog
+  ? posthogApiHost(config.integrations.analytics.posthog)
+  : undefined;
+const rybbit = config.integrations.analytics.rybbit
+  ? rybbitAnalyticsScript(config.integrations.analytics.rybbit)
+  : undefined;
+const swetrix = config.integrations.analytics.swetrix
+  ? swetrixScript()
+  : undefined;
+const swetrixBootstrap = swetrix ? swetrixBootstrapScript() : undefined;
+const umami = config.integrations.analytics.umami
+  ? umamiAnalyticsScript(config.integrations.analytics.umami)
+  : undefined;
+const intercom = config.integrations.support.intercom
+  ? intercomBootstrapScript()
+  : undefined;
+const front = config.integrations.support.front ? frontChatScript() : undefined;
+const frontBootstrap = front ? frontChatBootstrapScript() : undefined;
+const chatwoot = config.integrations.support.chatwoot
+  ? chatwootBootstrapScript()
+  : undefined;
+const chaskiq = config.integrations.support.chaskiq
+  ? chaskiqBootstrapScript()
+  : undefined;
+const papercups = config.integrations.support.papercups
+  ? papercupsBootstrapScript()
+  : undefined;
+const typebot = config.integrations.support.typebot
+  ? typebotBootstrapScript()
+  : undefined;
+const zammad = config.integrations.support.zammad
+  ? zammadChatScript(config.integrations.support.zammad)
+  : undefined;
+const zammadBootstrap = zammad ? zammadBootstrapScript() : undefined;
+
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <html lang="en" suppressHydrationWarning>
       <head>
+        {transcendGoogleConsentDefaults && (
+          <script
+            dangerouslySetInnerHTML={{
+              __html: transcendGoogleConsentDefaults,
+            }}
+          />
+        )}
+        {transcend && (
+          <script data-cfasync={transcend.dataCfasync} src={transcend.src} />
+        )}
         <meta name="color-scheme" content="light dark" />
         <meta name="referrer" content="strict-origin-when-cross-origin" />
+        {osano && <script src={osano.src} />}
+        {googleTagManager && (
+          <script
+            data-google-tag-manager-container-id={
+              config.integrations.analytics.gtm?.containerId
+            }
+            dangerouslySetInnerHTML={{ __html: googleTagManager }}
+          />
+        )}
         <script
           dangerouslySetInnerHTML={{
             __html: getThemeScript(THEME_STORAGE_KEY, config.mode),
           }}
         />
+        {adobe && <script async={adobe.async} src={adobe.src} />}
+        {amplitude && <script src={amplitude.src} />}
+        {clarity && (
+          <script
+            data-clarity-project-id={
+              config.integrations.analytics.clarity?.projectId
+            }
+            dangerouslySetInnerHTML={{ __html: clarity }}
+          />
+        )}
+        {clearbit && <script src={clearbit.src} />}
+        {fathom && (
+          <script
+            data-site={fathom.siteId}
+            data-spa={fathom.spa}
+            defer={fathom.defer}
+            src={fathom.src}
+          />
+        )}
+        {googleAnalytics && googleAnalyticsBootstrap && (
+          <>
+            <script async={googleAnalytics.async} src={googleAnalytics.src} />
+            <script
+              data-google-analytics-measurement-id={
+                config.integrations.analytics.ga4?.measurementId
+              }
+              dangerouslySetInnerHTML={{ __html: googleAnalyticsBootstrap }}
+            />
+          </>
+        )}
+        {heap && (
+          <script
+            data-heap-environment-id={
+              config.integrations.analytics.heap?.environmentId
+            }
+            dangerouslySetInnerHTML={{ __html: heap }}
+          />
+        )}
+        {hotjar && (
+          <script
+            data-hotjar-site-id={config.integrations.analytics.hotjar?.siteId}
+            data-hotjar-snippet-version={
+              config.integrations.analytics.hotjar?.snippetVersion
+            }
+            dangerouslySetInnerHTML={{ __html: hotjar }}
+          />
+        )}
+        {logRocket && logRocketBootstrap && (
+          <>
+            <script crossOrigin={logRocket.crossOrigin} src={logRocket.src} />
+            <script
+              data-logrocket-app-id={
+                config.integrations.analytics.logrocket?.appId
+              }
+              dangerouslySetInnerHTML={{ __html: logRocketBootstrap }}
+            />
+          </>
+        )}
+        {mixpanel && mixpanelBootstrap && (
+          <>
+            <script src={mixpanel.src} />
+            <script
+              data-mixpanel-project-token={
+                config.integrations.analytics.mixpanel?.projectToken
+              }
+              dangerouslySetInnerHTML={{ __html: mixpanelBootstrap }}
+            />
+          </>
+        )}
+        {openpanel && openpanelBootstrap && (
+          <>
+            <script
+              data-openpanel-api-url={
+                config.integrations.analytics.openpanel?.apiUrl
+              }
+              data-openpanel-client-id={
+                config.integrations.analytics.openpanel?.clientId
+              }
+              dangerouslySetInnerHTML={{ __html: openpanelBootstrap }}
+            />
+            <script
+              async={openpanel.async}
+              defer={openpanel.defer}
+              src={openpanel.src}
+            />
+          </>
+        )}
+        {openReplay && (
+          <script
+            data-openreplay-ingest-point={
+              config.integrations.analytics.openreplay?.ingestPoint
+            }
+            data-openreplay-project-key={
+              config.integrations.analytics.openreplay?.projectKey
+            }
+            dangerouslySetInnerHTML={{ __html: openReplay }}
+          />
+        )}
+        {pirsch && (
+          <script
+            data-code={pirsch.code}
+            defer={pirsch.defer}
+            src={pirsch.src}
+          />
+        )}
+        {plausible && (
+          <script
+            data-domain={plausible.domain}
+            defer={plausible.defer}
+            src={plausible.src}
+          />
+        )}
+        {posthog && posthogBootstrap && posthogHost && (
+          <>
+            <script src={posthog.src} />
+            <script
+              data-posthog-api-host={posthogHost}
+              data-posthog-project-api-key={
+                config.integrations.analytics.posthog?.projectApiKey
+              }
+              dangerouslySetInnerHTML={{ __html: posthogBootstrap }}
+            />
+          </>
+        )}
+        {rybbit && (
+          <script
+            data-site-id={rybbit.siteId}
+            defer={rybbit.defer}
+            src={rybbit.src}
+          />
+        )}
+        {umami && (
+          <script
+            data-website-id={umami.websiteId}
+            defer={umami.defer}
+            src={umami.src}
+          />
+        )}
+        {chaskiq && (
+          <script
+            data-chaskiq-app-id={config.integrations.support.chaskiq?.appId}
+            data-chaskiq-base-url={config.integrations.support.chaskiq?.baseUrl}
+            data-chaskiq-ws-url={config.integrations.support.chaskiq?.wsUrl}
+            dangerouslySetInnerHTML={{ __html: chaskiq }}
+          />
+        )}
+        {papercups && (
+          <script
+            data-papercups-base-url={
+              config.integrations.support.papercups?.baseUrl
+            }
+            data-papercups-inbox={config.integrations.support.papercups?.inbox}
+            data-papercups-token={config.integrations.support.papercups?.token}
+            dangerouslySetInnerHTML={{ __html: papercups }}
+          />
+        )}
+        {typebot && (
+          <script
+            data-heyo-typebot
+            data-typebot-api-host={config.integrations.support.typebot?.apiHost}
+            data-typebot-id={config.integrations.support.typebot?.typebot}
+            dangerouslySetInnerHTML={{ __html: typebot }}
+            type="module"
+          />
+        )}
         <script
           type="application/ld+json"
           dangerouslySetInnerHTML={{
@@ -67,12 +415,75 @@ export default function RootLayout({ children }: { children: ReactNode }) {
         />
       </head>
       <body>
+        {googleTagManagerNoScript && (
+          <noscript>
+            <iframe
+              height="0"
+              src={googleTagManagerNoScript}
+              style={{ display: "none", visibility: "hidden" }}
+              title="Google Tag Manager"
+              width="0"
+            />
+          </noscript>
+        )}
         <ThemeProvider
           defaultTheme={config.mode}
           storageKey={THEME_STORAGE_KEY}
         >
           {children}
         </ThemeProvider>
+        {swetrix && swetrixBootstrap && (
+          <>
+            <script defer={swetrix.defer} src={swetrix.src} />
+            <script
+              data-swetrix-api-url={
+                config.integrations.analytics.swetrix?.apiUrl
+              }
+              data-swetrix-project-id={
+                config.integrations.analytics.swetrix?.projectId
+              }
+              dangerouslySetInnerHTML={{ __html: swetrixBootstrap }}
+            />
+          </>
+        )}
+        {intercom && (
+          <script
+            data-intercom-app-id={config.integrations.support.intercom?.appId}
+            data-intercom-api-base={
+              config.integrations.support.intercom?.apiBase
+            }
+            dangerouslySetInnerHTML={{ __html: intercom }}
+          />
+        )}
+        {front && frontBootstrap && (
+          <>
+            <script src={front.src} />
+            <script
+              data-front-chat-id={config.integrations.support.front?.chatId}
+              dangerouslySetInnerHTML={{ __html: frontBootstrap }}
+            />
+          </>
+        )}
+        {chatwoot && (
+          <script
+            data-chatwoot-base-url={
+              config.integrations.support.chatwoot?.baseUrl
+            }
+            data-chatwoot-website-token={
+              config.integrations.support.chatwoot?.websiteToken
+            }
+            dangerouslySetInnerHTML={{ __html: chatwoot }}
+          />
+        )}
+        {zammad && zammadBootstrap && (
+          <>
+            <script src={zammad.src} />
+            <script
+              data-zammad-chat-id={config.integrations.support.zammad?.chatId}
+              dangerouslySetInnerHTML={{ __html: zammadBootstrap }}
+            />
+          </>
+        )}
       </body>
     </html>
   );

package/templates/next/content/api-overview.mdx

@@ -0,0 +1,20 @@
+---
+title: API overview
+description: Learn how to authenticate and explore the API reference.
+---
+
+# API overview
+
+The API reference is generated from `openapi.json`. Use the endpoint pages to
+enter parameters, send a request, and copy a cURL or JavaScript example.
+
+## Authentication
+
+The example API uses a Bearer token. Enter it once on any protected endpoint;
+Heyo Docs keeps it in this browser while you move between API pages.
+
+## Custom pages first
+
+This ordinary MDX page belongs to the OpenAPI group. Its section is configured
+before the generated endpoint sections, so it always appears at the top of the
+sidebar.

package/templates/next/content/assets/local-architecture.svg

@@ -0,0 +1,22 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="360" viewBox="0 0 960 360" fill="none">
+  <rect width="960" height="360" rx="24" fill="#F7F7F8"/>
+  <g fill="#FFFFFF" stroke="#D4D4D8" stroke-width="2">
+    <rect x="72" y="108" width="220" height="144" rx="18"/>
+    <rect x="370" y="108" width="220" height="144" rx="18"/>
+    <rect x="668" y="108" width="220" height="144" rx="18"/>
+  </g>
+  <g fill="#18181B" font-family="Arial, sans-serif" text-anchor="middle">
+    <text x="182" y="166" font-size="17" font-weight="700">Content</text>
+    <text x="182" y="194" font-size="14" fill="#71717A">MDX and assets</text>
+    <text x="480" y="166" font-size="17" font-weight="700">Build</text>
+    <text x="480" y="194" font-size="14" fill="#71717A">Vite bundles files</text>
+    <text x="778" y="166" font-size="17" font-weight="700">Documentation</text>
+    <text x="778" y="194" font-size="14" fill="#71717A">Static output</text>
+  </g>
+  <g stroke="#71717A" stroke-linecap="round" stroke-width="2">
+    <path d="M314 180h34"/>
+    <path d="m340 172 8 8-8 8"/>
+    <path d="M612 180h34"/>
+    <path d="m638 172 8 8-8 8"/>
+  </g>
+</svg>

package/templates/next/content/assets/quick-reference.txt

@@ -0,0 +1,5 @@
+Heyo Docs quick reference
+
+- Put MDX pages and local assets in content.
+- Use a relative path to bundle an image or downloadable file.
+- Use /path for assets in public.

package/templates/next/content/changelog.mdx

@@ -0,0 +1,38 @@
+---
+title: Changelog
+description: Mock release notes for the Heyo Docs example.
+---
+
+# Changelog
+
+<Update label="April 2026" tags={["New", "Documentation"]}>
+
+## Starter documentation
+
+New projects and runnable examples now include a structured Quickstart, basic
+configuration guide, deployment overview, and essential writing patterns.
+
+## Square API group
+
+The example navigation now keeps the pinned Square OpenAPI schema in its own
+group, making large-schema behaviour easy to inspect.
+
+</Update>
+
+<Update label="March 2026" tags={["Improved", "Developer experience"]}>
+
+## Clearer navigation
+
+External documentation links can display an icon, and sidebar groups now keep
+onboarding, API reference, and release notes separate.
+
+</Update>
+
+<Update label="February 2026" tags={["Fixed"]}>
+
+## More predictable previews
+
+Preview builds now validate configured routes before mock release notes are
+published.
+
+</Update>

package/templates/next/content/configuration.mdx

@@ -64,6 +64,40 @@ The order is meaningful: it controls the sidebar and the previous/next links at
 the end of each article. Use a page object with `title` and `src` when a
 sidebar entry should point to a page outside the local documentation.
 
+## AI chat
+
+Add `ai.chat` to enable a documentation-aware chat. `openai`, `claude`, and `grok`
+use the OpenAI, Anthropic, and xAI adapters respectively. Keep the key in a
+server environment variable; Heyo Docs sends it only from the chat endpoint.
+
+<CodeBlock language="ts" title="heyo-docs.config.ts">
+  {`ai: {
+  chat: {
+    provider: "openai",
+    key: process.env.OPENAI_API_KEY!,
+    model: "gpt-5-mini",
+    variant: "right", // "center" shows the compact prompt first
+    icon: "chat",
+    text: "AI Chat",
+    name: "Docs Assistant", // name shown in the drawer and message labels
+    placeholder: "Ask AI about the docs", // used in the compact prompt and drawer
+  },
+},`}
+</CodeBlock>
+
+`provider`, `key`, and `model` are required. The model must be an actual model
+identifier, not the provider name. `variant` defaults to `right`. `name`
+defaults to `AI`; it is used for the drawer title and the assistant's message
+label. `placeholder` defaults to
+`Ask AI about the docs` and is shared by the compact prompt and drawer input.
+The drawer stays open while
+readers navigate between documentation pages and does not block the rest of the
+page.
+
+Its chrome follows the selected documentation theme. For example, `grain` uses
+a full-height right panel with a left border, while the other themes keep a
+floating panel treatment.
+
 ## Verify the result
 
 Run the project's typecheck and build commands after changing configuration.

package/templates/next/content/essentials/callouts.mdx

@@ -1,36 +1,34 @@
 ---
 title: Callouts
-description: Highlight prerequisites, tips, warnings, and successful outcomes.
+description: Draw attention to a tip, warning, prerequisite, or result.
 ---
 
 # Callouts
 
-Use `Callout` when an important note should stand apart from the surrounding
-prose. It works well for a prerequisite, a preferred approach, a warning, or a
-successful result.
+Use a callout when a reader should not miss a detail.
 
-## Choose the right emphasis
-
-Use `note` or `info` for context, `tip` for a recommended approach, and
-`check` for a completed outcome. Reserve `warning` and `danger` for cases
-where missing the message has a real consequence.
+## Add a tip
 
 <Callout type="tip" title="Keep examples focused">
   Show one idea at a time so readers can apply it quickly.
 </Callout>
 
+## Choose a type
+
+| Type                  | Use it for             |
+| --------------------- | ---------------------- |
+| `info` or `note`      | Helpful context        |
+| `tip`                 | A recommended approach |
+| `check`               | A successful result    |
+| `warning` or `danger` | A real consequence     |
+
 <Callout type="warning" title="Preview before publishing">
-  Run the production build locally after changing navigation or MDX.
+  Run the production build after changing navigation or MDX.
 </Callout>
 
-## Add richer guidance
-
-Pass the message as children when it needs Markdown or another MDX component.
+## Keep it short
 
 <Callout type="info" title="Configuration and content work together">
-  Navigation belongs in <code>heyo-docs.config.ts</code>; page titles and
-  descriptions belong in the page frontmatter.
+  Navigation belongs in <code>heyo-docs.config.ts</code>. Titles and
+  descriptions belong in page frontmatter.
 </Callout>
-
-Keep each callout focused on one decision. A long sequence of status messages is
-usually clearer as regular sections or a numbered procedure.