@prudentbird/voxx 1.0.0

package/templates/changelog/release-list.tsx.tpl

@@ -0,0 +1,33 @@
+import { formatDate } from "@prudentbird/voxx-core";
+import type { Post, VoxxConfig } from "@prudentbird/voxx-core";
+
+export function ReleaseList({
+  posts,
+  config,
+}: {
+  posts: Post[];
+  config: VoxxConfig;
+}) {
+  if (posts.length === 0) {
+    return <p className="voxx-empty">No releases yet.</p>;
+  }
+
+  return (
+    <div className="voxx-releases">
+      {posts.map((post) => (
+        <section key={post.slug} id={post.slug} className="voxx-release">
+          <header className="voxx-release__header">
+            <h2 className="voxx-release__version">
+              <a href={`#${post.slug}`}>{post.version ? `v${post.version}` : post.title}</a>
+            </h2>
+            <time dateTime={post.date}>{formatDate(post.date, config.site.locale)}</time>
+          </header>
+          <div
+            className="voxx-prose"
+            dangerouslySetInnerHTML={{ __html: post.html }}
+          />
+        </section>
+      ))}
+    </div>
+  );
+}

package/templates/changelog/release.md.tpl

@@ -0,0 +1,15 @@
+---
+title: v0.1.0
+version: "0.1.0"
+date: {{DATE}}
+---
+
+### Added
+
+- Initial release. Each release is a markdown file named after its version
+  (`0.1.0.md`) — or set `version:` in frontmatter and name the file anything.
+
+### How this works
+
+Releases render newest-first on a single timeline page, and each one gets a
+stable anchor link. Run `voxx new "0.2.0"` to add the next release.

package/templates/docs/doc-page.tsx.tpl

@@ -0,0 +1,65 @@
+import Link from "next/link";
+import type { Post, VoxxConfig } from "@prudentbird/voxx-core";
+import { OnThisPage } from "./on-this-page";
+
+export function DocPage({
+  post,
+  config,
+  prev,
+  next,
+}: {
+  post: Post;
+  config: VoxxConfig;
+  prev?: Post | null;
+  next?: Post | null;
+}) {
+  const showToc = config.features.toc && post.toc.length > 0;
+
+  return (
+    <div className="voxx-layout">
+      <article className="voxx-article">
+        <header className="voxx-article__header">
+          <h1>{post.title}</h1>
+          {post.description ? (
+            <p className="voxx-article__meta">{post.description}</p>
+          ) : null}
+        </header>
+        <div
+          className="voxx-prose"
+          dangerouslySetInnerHTML={{ __html: post.html }}
+        />
+        {prev || next ? (
+          <nav className="voxx-pager">
+            {prev ? (
+              <Link href={prev.url} className="voxx-pager__link">
+                <span className="voxx-pager__label">Previous</span>
+                <span className="voxx-pager__title">{prev.title}</span>
+              </Link>
+            ) : (
+              <span />
+            )}
+            {next ? (
+              <Link
+                href={next.url}
+                className="voxx-pager__link voxx-pager__link--next"
+              >
+                <span className="voxx-pager__label">Next</span>
+                <span className="voxx-pager__title">{next.title}</span>
+              </Link>
+            ) : (
+              <span />
+            )}
+          </nav>
+        ) : null}
+      </article>
+
+      {showToc ? (
+        <aside className="voxx-aside">
+          <div className="voxx-aside__inner">
+            <OnThisPage toc={post.toc} />
+          </div>
+        </aside>
+      ) : null}
+    </div>
+  );
+}

package/templates/docs/getting-started-index.md.tpl

@@ -0,0 +1,9 @@
+---
+title: Getting Started
+description: Everything you need to go from zero to running.
+---
+
+This is a **section landing page** — it lives at `01-getting-started/index.md`,
+so it gives the "Getting Started" sidebar section its title and URL.
+
+Pages inside this folder appear nested under it in the sidebar.

package/templates/docs/index.md.tpl

@@ -0,0 +1,16 @@
+---
+title: Welcome
+description: What this documentation covers and how it's organized.
+---
+
+These docs are plain markdown files. The folder structure *is* the navigation:
+
+- Folders become sidebar sections, files become pages.
+- A numeric prefix (`01-install.md`) controls ordering without leaking into the URL.
+- An `index.md` inside a folder becomes that section's landing page.
+- Frontmatter `order: 2` overrides the filename prefix when you need it.
+
+## Editing this page
+
+This file is `index.md` at the root of your content directory — it's the page
+readers land on first. Replace this text with an overview of your project.

package/templates/docs/installation.md.tpl

@@ -0,0 +1,17 @@
+---
+title: Installation
+description: Install the project and verify it runs.
+---
+
+## Requirements
+
+- Node.js 20 or newer
+
+## Install
+
+```bash
+npm install your-package
+```
+
+The `01-` prefix on this file (`01-installation.md`) pins it to the top of its
+section; the URL stays clean: `/docs/getting-started/installation`.

package/templates/docs/layout-root.tsx.tpl

@@ -0,0 +1,52 @@
+import "./_voxx/voxx.css";
+{{GLOBALS_IMPORT}}
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+import Link from "next/link";
+import { buildNavTree } from "@prudentbird/voxx-core";
+import { getConfig, getPosts } from "./_voxx/data";
+import { SidebarNav } from "./_voxx/sidebar-nav";
+import { MobileNav } from "./_voxx/mobile-nav";
+import { ThemeToggle } from "./_voxx/theme-toggle";
+
+export async function generateMetadata(): Promise<Metadata> {
+  const config = await getConfig();
+  return {
+    title: {
+      default: config.site.title,
+      template: `%s · ${config.site.title}`,
+    },
+  };
+}
+
+export default async function DocsLayout({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  const [posts, config] = await Promise.all([getPosts(), getConfig()]);
+  const tree = buildNavTree(posts);
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <div className="voxx voxx-docs">
+          <aside className="voxx-docs__nav">
+            <div className="voxx-docs__nav-inner">
+              <div className="voxx-docs__nav-header">
+                <MobileNav items={tree} title={config.site.title} />
+                <Link href="{{BASE_PATH}}" className="voxx-docs__title">
+                  {config.site.title}
+                </Link>
+              </div>
+              <SidebarNav items={tree} />
+              <div className="voxx-docs__nav-footer">
+                <ThemeToggle />
+              </div>
+            </div>
+          </aside>
+          {children}
+        </div>
+      </body>
+    </html>
+  );
+}

package/templates/docs/layout.tsx.tpl

@@ -0,0 +1,37 @@
+import "./_voxx/voxx.css";
+{{GLOBALS_IMPORT}}
+import type { ReactNode } from "react";
+import Link from "next/link";
+import { buildNavTree } from "@prudentbird/voxx-core";
+import { getConfig, getPosts } from "./_voxx/data";
+import { SidebarNav } from "./_voxx/sidebar-nav";
+import { MobileNav } from "./_voxx/mobile-nav";
+import { ThemeToggle } from "./_voxx/theme-toggle";
+
+export default async function DocsLayout({
+  children,
+}: {
+  children: ReactNode;
+}) {
+  const [posts, config] = await Promise.all([getPosts(), getConfig()]);
+  const tree = buildNavTree(posts);
+  return (
+    <div className="voxx voxx-docs">
+      <aside className="voxx-docs__nav">
+        <div className="voxx-docs__nav-inner">
+          <div className="voxx-docs__nav-header">
+            <MobileNav items={tree} title={config.site.title} />
+            <Link href="{{BASE_PATH}}" className="voxx-docs__title">
+              {config.site.title}
+            </Link>
+          </div>
+          <SidebarNav items={tree} />
+          <div className="voxx-docs__nav-footer">
+            <ThemeToggle />
+          </div>
+        </div>
+      </aside>
+      {children}
+    </div>
+  );
+}

package/templates/docs/mobile-nav.tsx.tpl

@@ -0,0 +1,90 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { usePathname } from "next/navigation";
+import type { NavNode } from "@prudentbird/voxx-core";
+import { SidebarNav } from "./sidebar-nav";
+
+export function MobileNav({
+  items,
+  title,
+}: {
+  items: NavNode[];
+  title: string;
+}) {
+  const [open, setOpen] = useState(false);
+  const pathname = usePathname();
+
+  useEffect(() => {
+    setOpen(false);
+  }, [pathname]);
+
+  useEffect(() => {
+    if (!open) return;
+    document.body.style.overflow = "hidden";
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") setOpen(false);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => {
+      document.body.style.overflow = "";
+      window.removeEventListener("keydown", onKey);
+    };
+  }, [open]);
+
+  return (
+    <>
+      <button
+        type="button"
+        className="voxx-icon-button voxx-menu-button"
+        aria-label="Open navigation"
+        aria-expanded={open}
+        onClick={() => setOpen(true)}
+      >
+        <svg
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          aria-hidden="true"
+        >
+          <rect width="18" height="18" x="3" y="3" rx="2" />
+          <path d="M9 3v18" />
+        </svg>
+      </button>
+      {open ? (
+        <div className="voxx-drawer" role="dialog" aria-modal="true">
+          <div
+            className="voxx-drawer__overlay"
+            onClick={() => setOpen(false)}
+          />
+          <div className="voxx-drawer__panel">
+            <div className="voxx-drawer__header">
+              <span className="voxx-docs__title">{title}</span>
+              <button
+                type="button"
+                className="voxx-icon-button"
+                aria-label="Close navigation"
+                onClick={() => setOpen(false)}
+              >
+                <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+                  <path
+                    d="M6 6l12 12M18 6L6 18"
+                    stroke="currentColor"
+                    strokeWidth="2"
+                    strokeLinecap="round"
+                  />
+                </svg>
+              </button>
+            </div>
+            <div className="voxx-drawer__body">
+              <SidebarNav items={items} />
+            </div>
+          </div>
+        </div>
+      ) : null}
+    </>
+  );
+}

package/templates/docs/page.tsx.tpl

@@ -0,0 +1,50 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { buildSeo, serializeJsonLd } from "@prudentbird/voxx-core";
+import { getConfig, getPost, getPosts } from "../_voxx/data";
+import { toMetadata } from "../_voxx/metadata";
+import { DocPage } from "../_voxx/doc-page";
+
+type Params = { params: Promise<{ slug?: string[] }> };
+
+export async function generateStaticParams() {
+  const posts = await getPosts();
+  return posts.map((post) => ({ slug: post.path }));
+}
+
+export async function generateMetadata({ params }: Params): Promise<Metadata> {
+  const { slug = [] } = await params;
+  const [post, config] = await Promise.all([
+    getPost(slug.join("/")),
+    getConfig(),
+  ]);
+  if (!post) return {};
+  return toMetadata(buildSeo(post, config));
+}
+
+export default async function DocRoute({ params }: Params) {
+  const { slug = [] } = await params;
+  const [post, posts, config] = await Promise.all([
+    getPost(slug.join("/")),
+    getPosts(),
+    getConfig(),
+  ]);
+  if (!post) notFound();
+
+  const index = posts.findIndex((p) => p.url === post.url);
+  const prev = index > 0 ? posts[index - 1] : null;
+  const next = index >= 0 && index < posts.length - 1 ? posts[index + 1] : null;
+  const seo = buildSeo(post, config);
+
+  return (
+    <>
+      {config.seo.jsonLd && seo.jsonLd ? (
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: serializeJsonLd(seo.jsonLd) }}
+        />
+      ) : null}
+      <DocPage post={post} config={config} prev={prev} next={next} />
+    </>
+  );
+}

package/templates/docs/sidebar-nav.tsx.tpl

@@ -0,0 +1,39 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import type { NavNode } from "@prudentbird/voxx-core";
+
+export function SidebarNav({ items }: { items: NavNode[] }) {
+  const pathname = usePathname();
+  return (
+    <nav className="voxx-nav">
+      <NavList items={items} pathname={pathname} />
+    </nav>
+  );
+}
+
+function NavList({ items, pathname }: { items: NavNode[]; pathname: string }) {
+  return (
+    <ul className="voxx-nav__list">
+      {items.map((item) => (
+        <li key={`${item.url ?? ""}:${item.title}`}>
+          {item.url ? (
+            <Link
+              href={item.url}
+              className="voxx-nav__link"
+              data-active={pathname === item.url || undefined}
+            >
+              {item.title}
+            </Link>
+          ) : (
+            <span className="voxx-nav__section">{item.title}</span>
+          )}
+          {item.children.length > 0 ? (
+            <NavList items={item.children} pathname={pathname} />
+          ) : null}
+        </li>
+      ))}
+    </ul>
+  );
+}

package/templates/shared/content-version.ts.tpl

@@ -0,0 +1 @@
+export const CONTENT_VERSION = 0;

package/templates/shared/data.ts.tpl

@@ -0,0 +1,34 @@
+import "server-only";
+import {
+  findPost,
+  getPosts as coreGetPosts,
+  loadConfig as coreLoadConfig,
+  type Post,
+  type VoxxConfig,
+} from "@prudentbird/voxx-core";
+import { CONTENT_VERSION } from "./content-version";
+
+async function getPostsCached(version: number): Promise<Post[]> {
+  "use cache";
+  void version;
+  return coreGetPosts({{COLLECTION_ARG}});
+}
+
+export async function getPosts(): Promise<Post[]> {
+  return getPostsCached(CONTENT_VERSION);
+}
+
+async function getConfigCached(version: number): Promise<VoxxConfig> {
+  "use cache";
+  void version;
+  return coreLoadConfig();
+}
+
+export async function getConfig(): Promise<VoxxConfig> {
+  return getConfigCached(CONTENT_VERSION);
+}
+
+export async function getPost(slug: string): Promise<Post | null> {
+  const posts = await getPosts();
+  return findPost(posts, slug) ?? null;
+}

package/templates/shared/instrumentation.ts.tpl

@@ -0,0 +1,5 @@
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  const { registerContentWatcher } = await import("@prudentbird/voxx-core");
+  await registerContentWatcher();
+}

package/templates/shared/llms-full-route.ts.tpl

@@ -0,0 +1,9 @@
+import { renderLlmsFull } from "@prudentbird/voxx-core";
+import { getConfig, getPosts } from "{{DATA_IMPORT}}";
+
+export async function GET() {
+  const [posts, config] = await Promise.all([getPosts(), getConfig()]);
+  return new Response(renderLlmsFull(posts, config), {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}

package/templates/shared/llms-route.ts.tpl

@@ -0,0 +1,9 @@
+import { renderLlmsTxt } from "@prudentbird/voxx-core";
+import { getConfig, getPosts } from "{{DATA_IMPORT}}";
+
+export async function GET() {
+  const [posts, config] = await Promise.all([getPosts(), getConfig()]);
+  return new Response(renderLlmsTxt(posts, config), {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+  });
+}

package/templates/shared/metadata.ts.tpl

@@ -0,0 +1,39 @@
+import type { Metadata } from "next";
+import type { SeoData } from "@prudentbird/voxx-core";
+
+export function toMetadata(seo: SeoData): Metadata {
+  const metadata: Metadata = {
+    title: seo.title,
+    description: seo.description,
+    alternates: { canonical: seo.canonical },
+  };
+
+  if (seo.openGraph) {
+    metadata.openGraph = {
+      type: "article",
+      title: seo.openGraph.title,
+      description: seo.openGraph.description,
+      url: seo.openGraph.url,
+      siteName: seo.openGraph.siteName,
+      locale: seo.openGraph.locale,
+      images: seo.openGraph.images,
+      publishedTime: seo.openGraph.publishedTime,
+      modifiedTime: seo.openGraph.modifiedTime,
+      authors: seo.openGraph.authors,
+      tags: seo.openGraph.tags,
+    };
+  }
+
+  if (seo.twitter) {
+    metadata.twitter = {
+      card: "summary_large_image",
+      title: seo.twitter.title,
+      description: seo.twitter.description,
+      images: seo.twitter.images,
+      site: seo.twitter.site,
+      creator: seo.twitter.creator,
+    };
+  }
+
+  return metadata;
+}