feat(docs): add a Diátaxis documentation section to the public site

A new public /docs area covering the whole platform, organized by Diátaxis:
tutorials (learning), how-to guides (tasks), reference (facts), and explanation
(the why). 29 pages, each grounded in the actual routes, actions, schema, and
UI — verified against the code and corrected for accuracy (e.g. admin-only vs
admin+board gating, where the permissions matrix actually lives, how Stripe
reconciliation matches).

Implementation:
- lib/docs/nav.ts is the single source of truth (categories + pages), driving
  the sidebar, static params, and prev/next.
- Content authored as content/docs/<category>/<slug>.md, read at build time
  (the routes are statically generated), rendered by <DocsMarkdown> — reuses the
  existing react-markdown/GFM stack, no new dependencies.
- (docs) route group with its own theme (docs.css) matching the public site's
  dark / monospace / lime aesthetic; sidebar with active-state, breadcrumb,
  prev/next, and a Diátaxis home. Public — signed-in users can read it too.
- "Docs" link added to the landing nav.

typecheck 0 · lint 0 errors · build ok (all /docs pages prerendered)
This commit is contained in:
Moheeb Zara
2026-08-05 00:42:42 -07:00
parent fc6adaf16e
commit 16229ae523
38 changed files with 2928 additions and 0 deletions
+344
View File
@@ -0,0 +1,344 @@
/* =============================================================================
* Docs section styling. Scoped under .docs-root so it never bleeds into the
* management app. Matches the public site (landing / resources): near-black
* surfaces, IBM Plex Mono UI, Libre Baskerville display, lime accent.
* ===========================================================================*/
.docs-root {
--doc-bg: #0c0c0c;
--doc-surface: #141414;
--doc-surface-2: #1a1a1a;
--doc-border: #262626;
--doc-border-soft: #1e1e1e;
--doc-text: #e8e8e8;
--doc-text-dim: #9a9a9a;
--doc-text-muted: #6a6a6a;
--doc-accent: #d4ff00;
min-height: 100dvh;
position: relative;
background: var(--doc-bg);
color: var(--doc-text);
font-family: var(--font-ibm-plex-mono), 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace;
font-size: 14px;
line-height: 1.6;
-webkit-font-smoothing: antialiased;
}
.docs-root ::selection {
background: var(--doc-accent);
color: var(--doc-bg);
}
.docs-grid-bg {
position: fixed;
inset: 0;
z-index: 0;
pointer-events: none;
background-image:
linear-gradient(to right, rgba(255, 255, 255, 0.02) 1px, transparent 1px),
linear-gradient(to bottom, rgba(255, 255, 255, 0.02) 1px, transparent 1px);
background-size: 64px 64px;
mask-image: radial-gradient(ellipse 100% 60% at 50% 0%, #000 40%, transparent 100%);
}
.docs-root > *:not(.docs-grid-bg) {
position: relative;
z-index: 1;
}
/* ---- Header ------------------------------------------------------------- */
.docs-header {
position: sticky;
top: 0;
z-index: 20;
border-bottom: 1px solid var(--doc-border);
background: color-mix(in srgb, var(--doc-bg) 88%, transparent);
backdrop-filter: blur(8px);
}
.docs-header-inner {
max-width: 1280px;
margin: 0 auto;
padding: 0 24px;
height: 56px;
display: flex;
align-items: center;
justify-content: space-between;
gap: 16px;
}
.docs-wordmark {
display: inline-flex;
align-items: center;
gap: 8px;
font-weight: 500;
letter-spacing: -0.01em;
color: var(--doc-text);
}
.docs-wordmark .doc-accent { color: var(--doc-accent); }
.docs-header-links {
display: flex;
align-items: center;
gap: 18px;
font-size: 13px;
}
.docs-header-links a { color: var(--doc-text-dim); transition: color 0.12s; }
.docs-header-links a:hover { color: var(--doc-text); }
.docs-header-cta {
color: var(--doc-accent) !important;
border: 1px solid color-mix(in srgb, var(--doc-accent) 40%, transparent);
border-radius: 6px;
padding: 5px 12px;
}
.docs-header-cta:hover {
background: var(--doc-accent);
color: var(--doc-bg) !important;
}
/* ---- Shell (sidebar + content) ----------------------------------------- */
.docs-shell {
max-width: 1280px;
margin: 0 auto;
padding: 0 24px;
display: grid;
grid-template-columns: 248px minmax(0, 1fr);
gap: 48px;
align-items: start;
}
@media (max-width: 900px) {
.docs-shell { grid-template-columns: 1fr; gap: 0; }
}
/* ---- Sidebar ----------------------------------------------------------- */
.docs-sidebar {
position: sticky;
top: 56px;
align-self: start;
max-height: calc(100dvh - 56px);
overflow-y: auto;
padding: 32px 8px 48px 0;
}
@media (max-width: 900px) {
.docs-sidebar {
position: static;
max-height: none;
border-bottom: 1px solid var(--doc-border);
padding-bottom: 20px;
}
}
.docs-sidebar-group { margin-bottom: 26px; }
.docs-sidebar-group-label {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.12em;
color: var(--doc-text-muted);
margin-bottom: 10px;
padding-left: 10px;
}
.docs-sidebar-link {
display: block;
padding: 6px 10px;
border-radius: 6px;
color: var(--doc-text-dim);
font-size: 13px;
line-height: 1.4;
border-left: 2px solid transparent;
transition: color 0.12s, background 0.12s;
}
.docs-sidebar-link:hover { color: var(--doc-text); background: var(--doc-surface); }
.docs-sidebar-link.is-active {
color: var(--doc-accent);
background: var(--doc-surface);
border-left-color: var(--doc-accent);
}
/* ---- Content ----------------------------------------------------------- */
.docs-content {
min-width: 0;
padding: 40px 0 96px;
}
.docs-breadcrumb {
font-size: 12px;
color: var(--doc-text-muted);
margin-bottom: 14px;
display: flex;
gap: 8px;
align-items: center;
}
.docs-breadcrumb a { color: var(--doc-text-dim); }
.docs-breadcrumb a:hover { color: var(--doc-text); }
.docs-page-head { margin-bottom: 8px; }
.docs-eyebrow {
font-size: 11px;
text-transform: uppercase;
letter-spacing: 0.14em;
color: var(--doc-accent);
}
.docs-page-title {
font-family: var(--font-libre-baskerville), Georgia, serif;
font-size: clamp(28px, 4vw, 38px);
line-height: 1.12;
font-weight: 700;
margin: 8px 0 6px;
color: #fff;
}
.docs-page-summary { color: var(--doc-text-dim); font-size: 15px; max-width: 60ch; }
.docs-rule { border: none; border-top: 1px solid var(--doc-border); margin: 28px 0; }
/* ---- Prose ------------------------------------------------------------- */
.docs-prose { max-width: 72ch; color: var(--doc-text); }
.docs-prose > *:first-child { margin-top: 0; }
.docs-prose h1,
.docs-prose h2,
.docs-prose h3,
.docs-prose h4 {
color: #fff;
font-weight: 600;
letter-spacing: -0.01em;
scroll-margin-top: 72px;
}
.docs-prose h1 { font-size: 24px; margin: 40px 0 14px; }
.docs-prose h2 {
font-size: 20px;
margin: 38px 0 12px;
padding-bottom: 8px;
border-bottom: 1px solid var(--doc-border-soft);
}
.docs-prose h3 { font-size: 16px; margin: 28px 0 8px; }
.docs-prose h4 { font-size: 14px; margin: 22px 0 6px; color: var(--doc-text); }
.docs-prose p { margin: 14px 0; }
.docs-prose a { color: var(--doc-accent); text-decoration: underline; text-underline-offset: 2px; }
.docs-prose a:hover { text-decoration: none; }
.docs-prose strong { color: #fff; font-weight: 600; }
.docs-prose em { font-style: italic; }
.docs-prose ul,
.docs-prose ol { margin: 14px 0; padding-left: 22px; }
.docs-prose li { margin: 6px 0; }
.docs-prose ul { list-style: none; }
.docs-prose ul > li { position: relative; }
.docs-prose ul > li::before {
content: '—';
position: absolute;
left: -22px;
color: var(--doc-text-muted);
}
.docs-prose ol { list-style: decimal; }
.docs-prose ol > li::marker { color: var(--doc-text-muted); }
.docs-prose code {
font-family: var(--font-ibm-plex-mono), ui-monospace, monospace;
font-size: 0.86em;
background: var(--doc-surface-2);
border: 1px solid var(--doc-border-soft);
border-radius: 4px;
padding: 1px 5px;
color: var(--doc-accent);
}
.docs-prose pre {
background: var(--doc-surface);
border: 1px solid var(--doc-border);
border-radius: 8px;
padding: 14px 16px;
margin: 16px 0;
overflow-x: auto;
}
.docs-prose pre code {
background: none;
border: none;
padding: 0;
color: var(--doc-text);
font-size: 12.5px;
line-height: 1.6;
}
.docs-prose blockquote {
margin: 16px 0;
padding: 2px 16px;
border-left: 3px solid var(--doc-accent);
background: var(--doc-surface);
border-radius: 0 6px 6px 0;
color: var(--doc-text-dim);
}
.docs-prose blockquote p { margin: 10px 0; }
.docs-prose hr { border: none; border-top: 1px solid var(--doc-border); margin: 28px 0; }
.docs-prose table {
width: 100%;
border-collapse: collapse;
margin: 18px 0;
font-size: 13px;
display: block;
overflow-x: auto;
}
.docs-prose th,
.docs-prose td {
border: 1px solid var(--doc-border);
padding: 8px 12px;
text-align: left;
vertical-align: top;
}
.docs-prose th { background: var(--doc-surface); color: #fff; font-weight: 600; }
/* ---- Prev / next ------------------------------------------------------- */
.docs-pager {
display: flex;
justify-content: space-between;
gap: 16px;
margin-top: 48px;
padding-top: 24px;
border-top: 1px solid var(--doc-border);
}
.docs-pager a {
display: block;
flex: 1;
padding: 14px 16px;
border: 1px solid var(--doc-border);
border-radius: 8px;
transition: border-color 0.12s, background 0.12s;
}
.docs-pager a:hover { border-color: var(--doc-accent); background: var(--doc-surface); }
.docs-pager .docs-pager-next { text-align: right; }
.docs-pager-dir { font-size: 11px; text-transform: uppercase; letter-spacing: 0.1em; color: var(--doc-text-muted); }
.docs-pager-title { color: var(--doc-text); margin-top: 4px; }
/* ---- Home -------------------------------------------------------------- */
.docs-home-hero { padding: 56px 0 32px; }
.docs-home-title {
font-family: var(--font-libre-baskerville), Georgia, serif;
font-size: clamp(34px, 5vw, 52px);
line-height: 1.06;
font-weight: 700;
color: #fff;
}
.docs-home-title em { color: var(--doc-accent); font-style: italic; }
.docs-home-lede { color: var(--doc-text-dim); font-size: 16px; max-width: 62ch; margin-top: 16px; }
.docs-cat-grid {
display: grid;
grid-template-columns: repeat(2, minmax(0, 1fr));
gap: 16px;
padding-bottom: 80px;
}
@media (max-width: 760px) { .docs-cat-grid { grid-template-columns: 1fr; } }
.docs-cat-card {
border: 1px solid var(--doc-border);
border-radius: 12px;
padding: 22px;
background: var(--doc-surface);
transition: border-color 0.12s;
}
.docs-cat-card:hover { border-color: color-mix(in srgb, var(--doc-accent) 45%, var(--doc-border)); }
.docs-cat-eyebrow { font-size: 11px; text-transform: uppercase; letter-spacing: 0.12em; color: var(--doc-accent); }
.docs-cat-title {
font-size: 20px;
font-weight: 600;
color: #fff;
margin: 8px 0 6px;
}
.docs-cat-diataxis { color: var(--doc-text-dim); font-size: 13px; margin-bottom: 14px; }
.docs-cat-list { display: flex; flex-direction: column; gap: 2px; }
.docs-cat-list a {
display: block;
padding: 6px 8px;
margin: 0 -8px;
border-radius: 6px;
color: var(--doc-text-dim);
font-size: 13px;
}
.docs-cat-list a:hover { color: var(--doc-text); background: var(--doc-surface-2); }
@@ -0,0 +1,86 @@
import Link from 'next/link'
import { notFound } from 'next/navigation'
import { DOC_CATEGORIES, findPage, flatPages } from '@/lib/docs/nav'
import { loadDocContent } from '@/lib/docs/load'
import { DocsMarkdown } from '@/components/docs/docs-markdown'
import { DocsSidebar } from '@/components/docs/docs-sidebar'
export function generateStaticParams() {
return DOC_CATEGORIES.flatMap(cat =>
cat.pages.map(page => ({ category: cat.id, slug: page.slug })),
)
}
export const dynamicParams = false
type Params = { category: string; slug: string }
export async function generateMetadata({ params }: { params: Promise<Params> }) {
const { category, slug } = await params
const found = findPage(category, slug)
if (!found) return {}
return { title: found.page.title, description: found.page.summary }
}
export default async function DocPage({ params }: { params: Promise<Params> }) {
const { category, slug } = await params
const found = findPage(category, slug)
if (!found) notFound()
const { category: cat, page } = found
const content = await loadDocContent(cat.id, page.slug)
const flat = flatPages()
const idx = flat.findIndex(p => p.categoryId === cat.id && p.slug === page.slug)
const prev = idx > 0 ? flat[idx - 1] : null
const next = idx >= 0 && idx < flat.length - 1 ? flat[idx + 1] : null
return (
<main className="docs-shell">
<DocsSidebar />
<article className="docs-content">
<nav className="docs-breadcrumb" aria-label="Breadcrumb">
<Link href="/docs">Docs</Link>
<span>/</span>
<span>{cat.label}</span>
</nav>
<header className="docs-page-head">
<p className="docs-eyebrow">{cat.label}</p>
<h1 className="docs-page-title">{page.title}</h1>
<p className="docs-page-summary">{page.summary}</p>
</header>
<hr className="docs-rule" />
{content ? (
<DocsMarkdown content={content} />
) : (
<div className="docs-prose">
<p style={{ color: 'var(--doc-text-muted)' }}>
This page is being written. Check back shortly.
</p>
</div>
)}
<nav className="docs-pager" aria-label="Pagination">
{prev ? (
<Link href={`/docs/${prev.categoryId}/${prev.slug}`} className="docs-pager-prev">
<span className="docs-pager-dir">← Previous</span>
<span className="docs-pager-title">{prev.title}</span>
</Link>
) : (
<span />
)}
{next ? (
<Link href={`/docs/${next.categoryId}/${next.slug}`} className="docs-pager-next">
<span className="docs-pager-dir">Next →</span>
<span className="docs-pager-title">{next.title}</span>
</Link>
) : (
<span />
)}
</nav>
</article>
</main>
)
}
+53
View File
@@ -0,0 +1,53 @@
import Link from 'next/link'
import { DOC_CATEGORIES } from '@/lib/docs/nav'
export const metadata = {
title: 'Docs',
description:
'Everything you need to run your space with hackerspace.sh — organized as tutorials, how-to guides, reference, and explanation.',
}
export default function DocsHomePage() {
return (
<main className="docs-shell" style={{ gridTemplateColumns: '1fr' }}>
<div className="docs-content" style={{ padding: 0 }}>
<section className="docs-home-hero">
<p className="docs-eyebrow">Documentation</p>
<h1 className="docs-home-title">
Run your space, <em>documented</em>
</h1>
<p className="docs-home-lede">
Everything hackerspace.sh does, written down. Organized the{' '}
<a
href="https://diataxis.fr"
target="_blank"
rel="noopener noreferrer"
style={{ color: 'var(--doc-accent)', textDecoration: 'underline' }}
>
Diátaxis
</a>{' '}
way: learn with tutorials, get things done with how-to guides, look up the
details in reference, and understand the why in explanation.
</p>
</section>
<div className="docs-cat-grid">
{DOC_CATEGORIES.map(cat => (
<section key={cat.id} className="docs-cat-card">
<p className="docs-cat-eyebrow">{cat.tagline}</p>
<h2 className="docs-cat-title">{cat.label}</h2>
<p className="docs-cat-diataxis">{cat.diataxis}</p>
<div className="docs-cat-list">
{cat.pages.map(page => (
<Link key={page.slug} href={`/docs/${cat.id}/${page.slug}`}>
{page.title}
</Link>
))}
</div>
</section>
))}
</div>
</div>
</main>
)
}
+54
View File
@@ -0,0 +1,54 @@
import type { Metadata } from 'next'
import Link from 'next/link'
import { IBM_Plex_Mono, Libre_Baskerville } from 'next/font/google'
import { BrandMark } from '@/components/brand-mark'
import './docs.css'
const ibmPlexMono = IBM_Plex_Mono({
subsets: ['latin'],
weight: ['400', '500'],
variable: '--font-ibm-plex-mono',
display: 'swap',
})
const libreBaskerville = Libre_Baskerville({
subsets: ['latin'],
weight: ['400', '700'],
style: ['normal', 'italic'],
variable: '--font-libre-baskerville',
display: 'swap',
})
export const metadata: Metadata = {
title: {
default: 'Docs — hackerspace.sh',
template: '%s — hackerspace.sh docs',
},
description:
'Documentation for hackerspace.sh: tutorials, how-to guides, reference, and explanation for running your space.',
}
export default function DocsLayout({ children }: { children: React.ReactNode }) {
return (
<div className={`docs-root ${ibmPlexMono.variable} ${libreBaskerville.variable}`}>
<div className="docs-grid-bg" aria-hidden="true" />
<header className="docs-header">
<div className="docs-header-inner">
<Link href="/docs" className="docs-wordmark" aria-label="hackerspace.sh docs">
<BrandMark className="w-5 h-5" style={{ color: 'var(--doc-accent)' }} />
<span>
hackerspace<span className="doc-accent">.sh</span>{' '}
<span style={{ color: 'var(--doc-text-muted)' }}>/ docs</span>
</span>
</Link>
<nav className="docs-header-links">
<Link href="/">Home</Link>
<Link href="/resources" className="hidden sm:inline">Resources</Link>
<Link href="/dashboard" className="docs-header-cta">Open app →</Link>
</nav>
</div>
</header>
{children}
</div>
)
}
+1
View File
@@ -44,6 +44,7 @@ export default async function LandingPage() {
<span>hackerspace<span style={{ color: 'var(--ln-accent)' }}>.sh</span></span>
</Link>
<div className="landing-nav-links">
<Link href="/docs" className="hidden sm:inline">Docs</Link>
<Link href="/resources" className="hidden sm:inline">Resources</Link>
<a
href="https://github.com/virgilvox/hackerspace-management"