chore: setting up pipeline to deploy docs

Author: jeafreezy

docs/.dockerignore

@@ -0,0 +1,6 @@
+node_modules
+.next
+.source
+.git
+*.tsbuildinfo
+.env*

docs/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+.next/
+.source/
+out/
+*.tsbuildinfo
+.env*.local
+public/brand/
+!lib/
+!lib/**

docs/.nvmrc

@@ -0,0 +1 @@
+22

docs/Dockerfile

@@ -0,0 +1,20 @@
+# Build context is docs/, not the repository root.
+FROM node:22-alpine AS build
+WORKDIR /app
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm install --global pnpm@9.8.0
+COPY package.json pnpm-lock.yaml source.config.ts ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm check && pnpm build
+
+FROM node:22-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 HOSTNAME=0.0.0.0 PORT=3000
+COPY --from=build --chown=node:node /app/.next/standalone ./
+COPY --from=build --chown=node:node /app/.next/static ./.next/static
+COPY --from=build --chown=node:node /app/public ./public
+USER node
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 CMD node -e "fetch('http://127.0.0.1:3000/superstac').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "server.js"]

docs/README.md

@@ -0,0 +1,53 @@
+# SuperSTAC documentation
+
+A Fumadocs / Next.js site for **https://spatialnode.com/superstac**, with the approved logo, a custom landing page, search, light/dark themes, and Python/Rust/CLI guides. Source content lives in `content/docs`; branding originals stay in `assets` for the repository READMEs.
+
+## Develop
+
+Use Node **22.19+** (the latest Node 22 LTS patch is recommended).
+
+```bash
+cd docs
+nvm use
+npm install --global pnpm@9.8.0
+pnpm install --frozen-lockfile
+pnpm dev
+```
+
+Open **http://localhost:3000/superstac**. The reference pages start at `/superstac/docs`. The `/superstac` base path is intentionally enabled in development so broken asset and search URLs can be caught before deployment.
+
+```bash
+pnpm check
+pnpm build
+pnpm start
+# In another terminal, while the production server is running:
+pnpm test:links
+```
+
+`test:links` visits all authored docs routes, checks rendered internal links and assets, and exercises the search endpoint. Set `DOCS_TEST_ORIGIN` if the server is on another port.
+
+## Authoring
+
+- Add Markdown or MDX pages in `content/docs`.
+- Set `title` and `description` in frontmatter and order pages in each folder's `meta.json`.
+- Link between docs using `/docs/...`. Next.js adds `/superstac` for these links.
+- Public asset/download URLs use `/superstac/...` explicitly; plain image URLs do not receive Next.js base-path handling.
+- Edit the complete downloadable YAML in `public/examples/superstac.yml` and keep the quickstart snippet in sync.
+- Build hooks copy the two approved SVGs from `assets` to `public/brand`. Do not edit generated copies.
+- The Spatialnode footer badge is in `public/powered-by-spatialnode.svg`; its dark variant preserves the paths with white lettering and a dark background. Both follow the site's theme toggle.
+- The runnable Python notebook lives in `public/notebooks/superstac-python-quickstart.ipynb`, served at `/superstac/notebooks/superstac-python-quickstart.ipynb`. Keep this single source of truth free of saved outputs, execution counts, credentials, and personal runtime metadata. Its documentation page is `content/docs/python/notebook.mdx`.
+- Verify examples against the source when the alpha API changes. The docs record current implementation behavior, including limitations; they do not promise future features.
+
+Commit `pnpm-lock.yaml` whenever dependencies change. The Docker build uses pnpm 9.8.0 with `--frozen-lockfile`; dependency drift fails the build.
+
+## Python notebook
+
+Download [the notebook](public/notebooks/superstac-python-quickstart.ipynb) and upload it to Colab, or open it locally with Jupyter. Its cells install the Python dependencies when the reader runs them, search two public catalogs, show a footprint map, and export a ZIP of the results. They have not been executed against live catalogs here.
+
+The direct **Open in Colab** links target this file on GitHub's `main` branch and become usable after it is pushed there. Before publishing an updated notebook, run all cells in a fresh runtime, check the diagnostics and downloaded results, then clear outputs and execution counts before saving it back to the repository.
+
+## GitHub deployment automation
+
+[Deploy docs](../.github/workflows/docs-deploy.yml) runs on **published GitHub releases**, including prereleases, and through **Actions → Deploy docs → Run workflow**. Ordinary pushes and tag creation alone do not deploy. Publish a release only when its corresponding package is available; the workflow does not publish packages or wait for a separate package-publishing workflow.
+
+The workflow checks out the release tag or the manually supplied Git ref. It builds an AMD64 image, runs the Dockerfile's type check and production build, starts the resulting container, and checks pages, links, assets, search, and the 404 response. Only then does it publish to GHCR and deploy through the Coolify API. Use an x86-64 Coolify server for this workflow; an ARM server needs a matching runner/image platform.

docs/app/api/search/route.ts

@@ -0,0 +1,4 @@
+import { source } from '@/lib/source';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+export const { GET } = createFromSource(source, { language: 'english' });

docs/app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,31 @@
+import { source } from '@/lib/source';
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
+import { notFound } from 'next/navigation';
+import { getMDXComponents } from '@/mdx-components';
+import type { Metadata } from 'next';
+import { PoweredBySpatialnode } from '@/components/powered-by-spatialnode';
+
+type Props = { params: Promise<{ slug?: string[] }> };
+export default async function Page({ params }: Props) {
+  const { slug } = await params;
+  const page = source.getPage(slug);
+  if (!page) notFound();
+  const MDX = page.data.body;
+  return (
+    <DocsPage toc={page.data.toc}>
+      <DocsTitle>{page.data.title}</DocsTitle>
+      <DocsDescription>{page.data.description}</DocsDescription>
+      <DocsBody><MDX components={getMDXComponents()} /></DocsBody>
+      <div className="doc-endnote">
+        <PoweredBySpatialnode/>
+        <a href={`https://github.com/spatialnode/superstac/edit/main/docs/content/docs/${page.path}`}>Edit this page ↗</a>
+      </div>
+    </DocsPage>
+  );
+}
+export function generateStaticParams() { return source.generateParams(); }
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const page = source.getPage((await params).slug);
+  if (!page) notFound();
+  return { title: page.data.title, description: page.data.description, alternates: { canonical: `/superstac${page.url}` } };
+}

docs/app/docs/layout.tsx

@@ -0,0 +1,11 @@
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import { source } from '@/lib/source';
+import { baseOptions } from '@/lib/layout.shared';
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    <DocsLayout {...baseOptions()} tree={source.getPageTree()} sidebar={{ banner: <div className="sidebar-version"><span className="tiny-dot" /> v0.1 · Alpha</div> }}>
+      {children}
+    </DocsLayout>
+  );
+}

docs/app/global.css

@@ -0,0 +1,22 @@
+import type { Metadata } from 'next';
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import './global.css';
+
+export const metadata: Metadata = {
+  metadataBase: new URL('https://spatialnode.com'),
+  title: { default: 'SuperSTAC — Many catalogs. One search.', template: '%s | SuperSTAC' },
+  description: 'Search across STAC catalogs through one interface, with Python, Rust, or the command line. A Spatialnode open-source project.',
+  icons: { icon: '/superstac/favicon.svg' },
+};
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <RootProvider theme={{ storageKey: 'superstac-theme' }} search={{ options: { api: '/superstac/api/search' } }}>
+          {children}
+        </RootProvider>
+      </body>
+    </html>
+  );
+}