@heyo-sh/create-heyo-docs 1.0.1 → 2.0.0

package/templates/astro/content/openapi.json

@@ -1,278 +0,0 @@
-{
-  "openapi": "3.1.0",
-  "info": {
-    "title": "Planet API",
-    "version": "1.0.0",
-    "description": "An example API used by the Heyo Docs React Router demo."
-  },
-  "servers": [
-    {
-      "url": "https://api.example.com/v1",
-      "description": "Example production API"
-    }
-  ],
-  "security": [
-    {
-      "BearerAuth": []
-    }
-  ],
-  "paths": {
-    "/organizations/{organizationId}/planets": {
-      "parameters": [
-        {
-          "name": "organizationId",
-          "in": "path",
-          "required": true,
-          "description": "The organization that owns the planets.",
-          "schema": {
-            "type": "string",
-            "example": "org_123"
-          }
-        }
-      ],
-      "get": {
-        "operationId": "listPlanets",
-        "summary": "List planets",
-        "description": "Returns the planets that belong to an organization.",
-        "tags": ["Planets"],
-        "parameters": [
-          {
-            "name": "limit",
-            "in": "query",
-            "description": "Maximum number of records to return.",
-            "schema": {
-              "type": "integer",
-              "default": 20
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "A page of planets.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "type": "array",
-                  "items": {
-                    "$ref": "#/components/schemas/Planet"
-                  }
-                }
-              }
-            }
-          }
-        }
-      },
-      "post": {
-        "operationId": "createPlanet",
-        "summary": "Create a planet",
-        "description": "Creates a planet inside an organization.",
-        "tags": ["Planets"],
-        "requestBody": {
-          "required": true,
-          "description": "The planet to create.",
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PlanetInput"
-              }
-            }
-          }
-        },
-        "responses": {
-          "201": {
-            "description": "The newly created planet.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Planet"
-                }
-              }
-            }
-          }
-        }
-      }
-    },
-    "/organizations/{organizationId}/planets/{planetId}": {
-      "parameters": [
-        {
-          "name": "organizationId",
-          "in": "path",
-          "required": true,
-          "description": "The organization that owns the planet.",
-          "schema": {
-            "type": "string",
-            "example": "org_123"
-          }
-        },
-        {
-          "name": "planetId",
-          "in": "path",
-          "required": true,
-          "description": "The planet identifier.",
-          "schema": {
-            "type": "string",
-            "example": "planet_earth"
-          }
-        }
-      ],
-      "get": {
-        "operationId": "getPlanet",
-        "summary": "Get a planet",
-        "description": "Returns one planet by ID.",
-        "tags": ["Planets"],
-        "responses": {
-          "200": {
-            "description": "The requested planet.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Planet"
-                }
-              }
-            }
-          },
-          "404": {
-            "description": "Planet not found."
-          }
-        }
-      },
-      "put": {
-        "operationId": "replacePlanet",
-        "summary": "Replace a planet",
-        "description": "Replaces all editable planet values.",
-        "tags": ["Planets"],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PlanetInput"
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "The updated planet.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Planet"
-                }
-              }
-            }
-          }
-        }
-      },
-      "patch": {
-        "operationId": "updatePlanet",
-        "summary": "Update a planet",
-        "description": "Updates one or more planet fields.",
-        "tags": ["Planets"],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/PlanetPatch"
-              }
-            }
-          }
-        },
-        "responses": {
-          "200": {
-            "description": "The updated planet.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/Planet"
-                }
-              }
-            }
-          }
-        }
-      },
-      "delete": {
-        "operationId": "deletePlanet",
-        "summary": "Delete a planet",
-        "description": "Permanently removes a planet from an organization.",
-        "tags": ["Planets"],
-        "parameters": [
-          {
-            "name": "hardDelete",
-            "in": "query",
-            "description": "Also remove historical records.",
-            "schema": {
-              "type": "boolean",
-              "default": false
-            }
-          }
-        ],
-        "responses": {
-          "204": {
-            "description": "Planet deleted."
-          },
-          "404": {
-            "description": "Planet not found."
-          }
-        }
-      }
-    }
-  },
-  "components": {
-    "securitySchemes": {
-      "BearerAuth": {
-        "type": "http",
-        "scheme": "bearer",
-        "bearerFormat": "JWT"
-      }
-    },
-    "schemas": {
-      "Planet": {
-        "type": "object",
-        "required": ["id", "name", "classification"],
-        "properties": {
-          "id": {
-            "type": "string",
-            "example": "planet_earth"
-          },
-          "name": {
-            "type": "string",
-            "example": "Earth"
-          },
-          "classification": {
-            "type": "string",
-            "enum": ["terrestrial", "gas-giant", "ice-giant"]
-          }
-        }
-      },
-      "PlanetInput": {
-        "type": "object",
-        "required": ["name", "classification"],
-        "properties": {
-          "name": {
-            "type": "string",
-            "example": "Mars"
-          },
-          "classification": {
-            "type": "string",
-            "enum": ["terrestrial", "gas-giant", "ice-giant"]
-          }
-        }
-      },
-      "PlanetPatch": {
-        "type": "object",
-        "properties": {
-          "name": {
-            "type": "string",
-            "example": "New Mars"
-          },
-          "classification": {
-            "type": "string",
-            "enum": ["terrestrial", "gas-giant", "ice-giant"]
-          }
-        }
-      }
-    }
-  }
-}

package/templates/astro/content/quickstart.mdx

@@ -1,60 +0,0 @@
----
-title: Quickstart
-description: Create, run, and understand your Heyo Docs project.
----
-
-# Quickstart
-
-A new Heyo Docs project is a complete documentation site: MDX files provide the
-content, `heyo-docs.config.ts` defines the site model, and your selected
-framework renders the finished experience.
-
-## Create a project
-
-Use the creator with the package manager you already use. It asks for a project
-name, framework, deployment target, theme, and package manager, then creates a
-ready-to-run application.
-
-<CodeBlockGroup defaultValue="bun" variant="line">
-  <CodeBlock language="bash" title="bun">
-    {"bun create @heyo-sh/heyo-docs"}
-  </CodeBlock>
-  <CodeBlock language="bash" title="npm">
-    {"npm create @heyo-sh/heyo-docs@latest"}
-  </CodeBlock>
-  <CodeBlock language="bash" title="pnpm">
-    {"pnpm create @heyo-sh/heyo-docs"}
-  </CodeBlock>
-  <CodeBlock language="bash" title="yarn">
-    {"yarn dlx @heyo-sh/create-heyo-docs"}
-  </CodeBlock>
-</CodeBlockGroup>
-
-When the command finishes, move into the new directory and run the development
-command printed by the creator. The local server rebuilds the documentation
-when you change either content or configuration.
-
-## How the pieces fit together
-
-1. **Content** lives in the `content` directory. Every `.mdx` file becomes a
-   documentation route.
-2. **Configuration** in `heyo-docs.config.ts` gives the site its name, theme,
-   navigation order, and public metadata.
-3. **The framework app** loads the same model during development and production
-   builds, so the sidebar, search, routes, and adjacent-page links stay in sync.
-
-Create a new file such as `content/guides/deployment.mdx` to add the
-`/guides/deployment` route. Add that path to a navigation section when the
-page should appear in the sidebar.
-
-## Make your first change
-
-Update the title and description in the frontmatter of `content/index.mdx`,
-then refresh the browser. Use [Basic Configuration](/configuration) to adjust
-the site model and [Text Styling](/essentials/text-styling) for writing the
-page itself.
-
-<Callout type="tip" title="One source of truth">
-  Keep navigation in <code>heyo-docs.config.ts</code> and page-specific details
-  in MDX frontmatter. The build validates both before publishing.
-</Callout>

package/templates/astro/src/components/theme-provider.tsx

@@ -1,106 +0,0 @@
-import {
-  createContext,
-  useContext,
-  useEffect,
-  useState,
-  type ReactNode,
-} from "react";
-
-import {
-  applyTheme,
-  DEFAULT_THEME,
-  getStoredTheme,
-  type ResolvedTheme,
-  THEME_STORAGE_KEY,
-  type Theme,
-} from "../lib/theme";
-
-type ThemeProviderProps = {
-  children: ReactNode;
-  defaultTheme?: Theme;
-  storageKey?: string;
-};
-
-type ThemeProviderState = {
-  theme: Theme;
-  resolvedTheme: ResolvedTheme;
-  mounted: boolean;
-  setTheme: (theme: Theme) => void;
-};
-
-const ThemeProviderContext = createContext<ThemeProviderState | undefined>(
-  undefined,
-);
-
-export function ThemeProvider({
-  children,
-  defaultTheme = DEFAULT_THEME,
-  storageKey = THEME_STORAGE_KEY,
-}: ThemeProviderProps) {
-  const [theme, setThemeState] = useState<Theme>(defaultTheme);
-  const [resolvedTheme, setResolvedTheme] = useState<ResolvedTheme>(
-    defaultTheme === "system" ? "light" : defaultTheme,
-  );
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-    const syncTheme = () => {
-      const nextTheme = getStoredTheme(storageKey, defaultTheme);
-
-      setThemeState(nextTheme);
-      setResolvedTheme(applyTheme(nextTheme));
-    };
-
-    syncTheme();
-
-    const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
-    const handleSystemThemeChange = () => {
-      const nextTheme = getStoredTheme(storageKey, defaultTheme);
-      setResolvedTheme(applyTheme(nextTheme));
-    };
-    const handleStorage = (event: StorageEvent) => {
-      if (event.key !== null && event.key !== storageKey) return;
-      syncTheme();
-    };
-
-    mediaQuery.addEventListener("change", handleSystemThemeChange);
-    window.addEventListener("storage", handleStorage);
-    setMounted(true);
-
-    return () => {
-      mediaQuery.removeEventListener("change", handleSystemThemeChange);
-      window.removeEventListener("storage", handleStorage);
-    };
-  }, [defaultTheme, storageKey]);
-
-  const value = {
-    theme,
-    resolvedTheme,
-    mounted,
-    setTheme: (nextTheme: Theme) => {
-      try {
-        window.localStorage.setItem(storageKey, nextTheme);
-      } catch {
-        // The requested preference still applies when storage is unavailable.
-      }
-
-      setThemeState(nextTheme);
-      setResolvedTheme(applyTheme(nextTheme));
-    },
-  };
-
-  return (
-    <ThemeProviderContext.Provider value={value}>
-      {children}
-    </ThemeProviderContext.Provider>
-  );
-}
-
-export function useTheme() {
-  const context = useContext(ThemeProviderContext);
-
-  if (context === undefined)
-    throw new Error("useTheme must be used within a ThemeProvider");
-
-  return context;
-}

package/templates/astro/src/lib/seo.ts

@@ -1,221 +0,0 @@
-import {
-  navigationGroupContainsPath,
-  navigationPages,
-  navigationSectionPathForPath,
-  type ChangelogGroupConfig,
-  type DocsPage,
-  type HeyoDocsConfig,
-  type NavigationGroup,
-  type OpenApiEndpoint,
-} from "@heyo-sh/heyo-docs";
-
-interface DocsSeoInput {
-  config: HeyoDocsConfig;
-  pathname: string;
-  page?: DocsPage;
-  endpoint?: OpenApiEndpoint;
-  changelogGroup?: ChangelogGroupConfig;
-  navigation?: NavigationGroup[];
-}
-
-function canonicalFor(
-  config: HeyoDocsConfig,
-  pathname: string,
-  page?: DocsPage,
-): string | undefined {
-  return (
-    page?.seo.canonical ??
-    (config.siteUrl ? `${config.siteUrl}${pathname}` : undefined)
-  );
-}
-
-function website(config: HeyoDocsConfig) {
-  return {
-    "@type": "WebSite",
-    name: config.title,
-    ...(config.siteUrl ? { url: config.siteUrl } : {}),
-  };
-}
-
-interface BreadcrumbItem {
-  label: string;
-  href?: string;
-}
-
-function breadcrumbItems(
-  navigation: NavigationGroup[] | undefined,
-  pathname: string,
-  title: string,
-  changelogGroup: ChangelogGroupConfig | undefined,
-): BreadcrumbItem[] {
-  if (changelogGroup) return [{ label: changelogGroup.group, href: pathname }];
-
-  const group = navigation?.find((candidate) =>
-    navigationGroupContainsPath(candidate, pathname),
-  );
-  const sections = group
-    ? navigationSectionPathForPath(group.sections, pathname)
-    : undefined;
-
-  if (!group) return [{ label: title, href: pathname }];
-
-  const groupHref = navigationPages(group.sections)[0]?.slug;
-  return [
-    { label: group.group, href: groupHref },
-    ...(sections ?? []).map((section) => ({
-      label: section.section,
-      href: navigationPages([section])[0]?.slug,
-    })),
-    { label: title, href: pathname },
-  ];
-}
-
-function absoluteUrl(siteUrl: string | undefined, href: string | undefined) {
-  if (!siteUrl || !href) return undefined;
-  if (/^https?:\/\//.test(href)) return href;
-  return new URL(href, `${siteUrl}/`).toString();
-}
-
-function breadcrumbs(
-  config: HeyoDocsConfig,
-  canonical: string | undefined,
-  title: string,
-  navigation: NavigationGroup[] | undefined,
-  pathname: string,
-  changelogGroup: ChangelogGroupConfig | undefined,
-) {
-  const items = breadcrumbItems(navigation, pathname, title, changelogGroup);
-
-  return {
-    "@context": "https://schema.org",
-    "@type": "BreadcrumbList",
-    itemListElement: [
-      { label: config.title, href: config.siteUrl },
-      ...items,
-    ].map((item, index, allItems) => {
-      const itemUrl =
-        index === allItems.length - 1
-          ? canonical
-          : absoluteUrl(config.siteUrl, item.href);
-      return {
-        "@type": "ListItem",
-        position: index + 1,
-        name: item.label,
-        ...(itemUrl ? { item: itemUrl } : {}),
-      };
-    }),
-  };
-}
-
-function endpointUrlTemplate(endpoint: OpenApiEndpoint) {
-  const server = endpoint.servers[0]?.replace(/\/$/, "");
-  return server ? `${server}${endpoint.path}` : endpoint.path;
-}
-
-function structuredData({
-  changelogGroup,
-  config,
-  endpoint,
-  page,
-  canonical,
-  description,
-  title,
-}: Omit<DocsSeoInput, "pathname"> & {
-  canonical?: string;
-  description: string;
-  title: string;
-}) {
-  if (endpoint) {
-    const entryPoint = {
-      "@type": "EntryPoint",
-      name:
-        endpoint.operationId ??
-        `${endpoint.method.toUpperCase()} ${endpoint.path}`,
-      httpMethod: endpoint.method.toUpperCase(),
-      urlTemplate: endpointUrlTemplate(endpoint),
-      ...(endpoint.requestBody?.contentType
-        ? { encodingType: endpoint.requestBody.contentType }
-        : {}),
-      ...(endpoint.responses[0]?.contentType
-        ? { contentType: endpoint.responses[0].contentType }
-        : {}),
-    };
-    return {
-      "@context": "https://schema.org",
-      "@type": "APIReference",
-      headline: title,
-      description,
-      ...(canonical ? { url: canonical } : {}),
-      isPartOf: website(config),
-      mainEntity: entryPoint,
-    };
-  }
-
-  if (page && changelogGroup) {
-    return {
-      "@context": "https://schema.org",
-      "@type": "CollectionPage",
-      headline: title,
-      description,
-      ...(canonical ? { url: canonical } : {}),
-      isPartOf: website(config),
-      ...(page.changelogUpdates?.length
-        ? {
-            hasPart: page.changelogUpdates.map((update) => ({
-              "@type": "TechArticle",
-              headline: update.label,
-              ...(update.tags.length
-                ? { keywords: update.tags.join(", ") }
-                : {}),
-              ...(canonical ? { url: `${canonical}#${update.id}` } : {}),
-            })),
-          }
-        : {}),
-    };
-  }
-
-  return {
-    "@context": "https://schema.org",
-    "@type": "TechArticle",
-    headline: title,
-    description,
-    ...(canonical ? { url: canonical } : {}),
-    isPartOf: website(config),
-  };
-}
-
-export function docsSeo(input: DocsSeoInput) {
-  const { changelogGroup, config, endpoint, navigation, page, pathname } =
-    input;
-  const title = page?.seo.title ?? `${endpoint!.title} | ${config.title}`;
-  const description =
-    page?.seo.description ??
-    endpoint?.description ??
-    `${endpoint!.method.toUpperCase()} ${endpoint!.path} API endpoint.`;
-  const canonical = canonicalFor(config, pathname, page);
-
-  return {
-    title,
-    description,
-    canonical,
-    structuredData: [
-      structuredData({
-        changelogGroup,
-        config,
-        endpoint,
-        page,
-        canonical,
-        description,
-        title,
-      }),
-      breadcrumbs(
-        config,
-        canonical,
-        page?.title ?? endpoint!.title,
-        navigation,
-        pathname,
-        changelogGroup,
-      ),
-    ],
-  };
-}