Skip to content

Build multi-page docs with navigation #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
julianduque wants to merge 1 commit into
base: gh-docs
Choose a base branch
from
Open

Build multi-page docs with navigation #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions app/docs/collaboration/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { DocsPager } from "@/components/docs/docs-pager";
import { FeatureList } from "@/components/docs/feature-list";
import { SectionHeading } from "@/components/docs/section-heading";
import { collaborationFeatures } from "@/lib/docs-content";

export const metadata = {
title: "Collaboration | NodeBooks Documentation",
description: "See how NodeBooks keeps teams aligned with presence, shared runtimes, and live feedback.",
};

# Collaboration

NodeBooks keeps everyone in the loop while experiments unfold. Real-time presence indicators, shared output streams, and session sharing remove the friction of pairing on notebooks remotely.

<SectionHeading id="presence">Presence-aware editing</SectionHeading>

Know who is editing a notebook and where their cursor is in real time. Inline comments and suggestions make asynchronous reviews feel collaborative.

<SectionHeading id="shared-output">Shared execution output</SectionHeading>

Notebook runs stream output to every participant, so you never wonder if a cell finished or failed. Broadcast a session during reviews or pair programming without screen sharing.

<FeatureList items={collaborationFeatures} />

<DocsPager slug="collaboration" />
51 changes: 51 additions & 0 deletions app/docs/getting-started/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
import { DocsPager } from "@/components/docs/docs-pager";
import { SectionHeading } from "@/components/docs/section-heading";
import { workflow } from "@/lib/content";

export const metadata = {
title: "Getting Started | NodeBooks Documentation",
description: "Install the NodeBooks CLI and create your first collaborative notebook workspace.",
};

# Getting Started

NodeBooks is distributed as a CLI so you can set up workspaces from any terminal. Follow these steps to install the tooling, initialize a project, and open the desktop or web client.

<SectionHeading id="install">Install the CLI</SectionHeading>

Install the CLI globally so the `nodebooks` command is always available. The installer handles downloading the latest runtime, linking the binary, and checking for required system dependencies.

```
npm install -g nodebooks
```

<SectionHeading id="create-workspace">Create a workspace</SectionHeading>

Run the interactive init command to scaffold a new space. The CLI prompts for a project name, notebook template, and optional GitHub connection so you can version your notebooks from day one.

<table>
<thead>
<tr>
<th>Step</th>
<th>Description</th>
<th>Command</th>
</tr>
</thead>
<tbody>
{workflow.map((step) => (
<tr key={step.title}>
<td className="font-medium text-foreground">{step.title}</td>
<td>{step.description}</td>
<td>
<code>{step.code}</code>
</td>
</tr>
))}
</tbody>
</table>

<SectionHeading id="connect-clients">Connect the clients</SectionHeading>

Once the workspace is ready, open it in the web or desktop client. Both connect to the same runtime so teams can swap devices without losing context. Future docs will cover authentication flows and workspace governance in more depth.

<DocsPager slug="getting-started" />
44 changes: 44 additions & 0 deletions app/docs/layout.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
import Link from "next/link";
import type { ReactNode } from "react";

import { docsPages } from "@/lib/docs-navigation";

import { SiteFooter } from "@/components/site-footer";
import { ThemeToggle } from "@/components/theme-toggle";
import { DocsSidebar } from "@/components/docs/sidebar";

export default function DocsLayout({ children }: { children: ReactNode }) {
return (
<div className="flex min-h-svh flex-col bg-background">
<header className="sticky top-0 z-40 border-b border-border/60 bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/75">
<div className="mx-auto flex w-full max-w-6xl items-center justify-between px-6 py-4">
<Link href="/" className="text-lg font-semibold text-foreground">
NodeBooks
</Link>
<div className="flex items-center gap-4 text-sm">
<Link
href="/#features"
className="hidden text-muted-foreground transition-colors hover:text-foreground sm:inline-flex"
>
Product
</Link>
<Link
href="/#screenshots"
className="hidden text-muted-foreground transition-colors hover:text-foreground sm:inline-flex"
>
Screenshots
</Link>
<ThemeToggle />
</div>
</div>
</header>
<div className="mx-auto flex w-full max-w-6xl flex-1 gap-8 px-6 py-12">
<nav className="hidden w-64 shrink-0 lg:block">
<DocsSidebar items={docsPages} />
</nav>
<main className="min-w-0 flex-1 pb-16 lg:pb-24">{children}</main>
</div>
<SiteFooter />
</div>
);
}
25 changes: 25 additions & 0 deletions app/docs/notebook-authoring/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { DocsPager } from "@/components/docs/docs-pager";
import { FeatureList } from "@/components/docs/feature-list";
import { SectionHeading } from "@/components/docs/section-heading";
import { notebookAuthoringFeatures } from "@/lib/docs-content";

export const metadata = {
title: "Notebook Authoring | NodeBooks Documentation",
description: "Compose Markdown, TypeScript, and interactive components in a single notebook surface.",
};

# Notebook Authoring

NodeBooks blends Markdown, runnable TypeScript, and reusable UI components so you can tell a complete story inside a single notebook. The authoring surface encourages experimentation without sacrificing polish.

<SectionHeading id="markdown-and-code">Markdown and code live together</SectionHeading>

Draft ideas in Markdown cells, then drop into TypeScript when you need dynamic behavior. AI-assisted suggestions accelerate repetitive coding tasks so you can focus on the narrative.

<SectionHeading id="rich-components">Rich components and visualizations</SectionHeading>

Use built-in charting, diagramming, and UI components to make findings stand out. Render interactive elements inline, prototype dashboards, or embed bespoke React components sourced from your design system.

<FeatureList items={notebookAuthoringFeatures} />

<DocsPager slug="notebook-authoring" />
27 changes: 27 additions & 0 deletions app/docs/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
import { DocsPager } from "@/components/docs/docs-pager";
import { SectionHeading } from "@/components/docs/section-heading";

export const metadata = {
title: "NodeBooks Documentation",
description: "Guides for building, collaborating, and shipping interactive Node.js notebooks.",
};

# NodeBooks Documentation

NodeBooks combines a friendly notebook surface with the power of Node.js so you can explore ideas, collaborate, and publish in a single tool. These docs outline the product pillars today and leave room for deeper guides as the platform evolves.

<SectionHeading id="how-to-use">How to use these docs</SectionHeading>

Use the sidebar to jump between key workflows. Each guide explains the why behind the feature set, highlights the current capabilities, and calls out the next pieces to document as the platform grows.

- [Getting Started](/docs/getting-started) walks through installing the CLI and initializing a workspace.
- [Notebook Authoring](/docs/notebook-authoring) focuses on writing Markdown, TypeScript, and visual outputs together.
- [Runtime & Dependencies](/docs/runtime-and-dependencies) covers the sandboxed execution model and dependency management.
- [Collaboration](/docs/collaboration) shows how real-time presence keeps teams in sync.
- [Publishing & Sharing](/docs/publishing) explains how to ship notebooks as public-facing sites.

<SectionHeading id="whats-next">What comes next</SectionHeading>

Future iterations of the documentation will dive into workspace governance, deployment pipelines, and custom component authoring. As new features ship, expand each section with tutorials, API references, and troubleshooting guides.

<DocsPager slug="overview" />
25 changes: 25 additions & 0 deletions app/docs/publishing/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { DocsPager } from "@/components/docs/docs-pager";
import { FeatureList } from "@/components/docs/feature-list";
import { SectionHeading } from "@/components/docs/section-heading";
import { publishingFeatures } from "@/lib/docs-content";

export const metadata = {
title: "Publishing & Sharing | NodeBooks Documentation",
description: "Publish notebooks as production-ready sites and share results securely.",
};

# Publishing & Sharing

Turn exploratory notebooks into polished deliverables without leaving the platform. NodeBooks handles build orchestration so you can focus on storytelling and distribution.

<SectionHeading id="ship-sites">Ship notebook sites</SectionHeading>

Publish notebooks directly to the web with a few clicks. Preview deployments in private spaces, collect feedback, and push live when the content is ready.

<SectionHeading id="iterate">Iterate with your team</SectionHeading>

Keep iterating on notebooks after they launch. Versioned deployments and workspace access controls let you refine docs, demos, and educational material safely.

<FeatureList items={publishingFeatures} />

<DocsPager slug="publishing" />
25 changes: 25 additions & 0 deletions app/docs/runtime-and-dependencies/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
import { DocsPager } from "@/components/docs/docs-pager";
import { FeatureList } from "@/components/docs/feature-list";
import { SectionHeading } from "@/components/docs/section-heading";
import { runtimeAndDependencyFeatures } from "@/lib/docs-content";

export const metadata = {
title: "Runtime & Dependencies | NodeBooks Documentation",
description: "Understand the sandboxed Node.js runtime and how to manage notebook-level dependencies.",
};

# Runtime & Dependencies

Every notebook executes inside an isolated Node.js sandbox tuned for TypeScript. This keeps experiments reproducible while still letting you install the packages and tools you rely on.

<SectionHeading id="node-runtime">Sandboxed Node.js runtime</SectionHeading>

Each notebook runs on demand with scoped environment variables, ensuring secrets never leak between projects. Streaming output keeps you informed about long-running tasks without leaving the page.

<SectionHeading id="dependencies">Manage dependencies per notebook</SectionHeading>

Install npm packages directly from a notebook cell or pin them in `package.json` for the entire workspace. NodeBooks keeps dependency state isolated so collaborators can explore without affecting production projects.

<FeatureList items={runtimeAndDependencyFeatures} />

<DocsPager slug="runtime-and-dependencies" />
84 changes: 84 additions & 0 deletions components/docs/docs-pager.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
import Link from "next/link";

import { ArrowLeft, ArrowRight } from "lucide-react";

import type { DocsPageSlug } from "@/lib/docs-navigation";
import { getAdjacentDocs } from "@/lib/docs-navigation";
import { cn } from "@/lib/utils";

interface DocsPagerProps {
slug: DocsPageSlug;
}

export function DocsPager({ slug }: DocsPagerProps) {
const { previous, next } = getAdjacentDocs(slug);

if (!previous && !next) {
return null;
}

return (
<div className="mt-16 border-t border-border/60 pt-8">
<div className="flex flex-col gap-4 sm:flex-row sm:gap-6">
{previous ? (
<PagerLink
direction="previous"
href={previous.href}
title={previous.title}
description={previous.description}
/>
) : null}
{next ? (
<PagerLink
direction="next"
href={next.href}
title={next.title}
description={next.description}
className={cn(!previous && "sm:ml-auto")}
/>
) : null}
</div>
</div>
);
}

interface PagerLinkProps {
direction: "previous" | "next";
href: string;
title: string;
description: string;
className?: string;
}

function PagerLink({ direction, href, title, description, className }: PagerLinkProps) {
const isNext = direction === "next";
const Icon = isNext ? ArrowRight : ArrowLeft;

return (
<Link
href={href}
className={cn(
"group flex flex-1 items-center gap-4 rounded-2xl border border-border/60 bg-card/40 p-5 transition hover:border-border",
"hover:bg-muted/40",
className,
)}
>
<span
aria-hidden
className={cn(
"flex size-10 shrink-0 items-center justify-center rounded-full border border-border/60 bg-background text-muted-foreground transition group-hover:border-border group-hover:text-foreground",
isNext && "order-3",
)}
>
<Icon className="size-4" />
</span>
<div className={cn("flex flex-1 flex-col", isNext && "items-end text-right")}>
<span className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">
{isNext ? "Next" : "Previous"}
</span>
<span className="text-sm font-semibold text-foreground">{title}</span>
<span className="text-xs text-muted-foreground">{description}</span>
</div>
</Link>
);
}
28 changes: 28 additions & 0 deletions components/docs/feature-list.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
import { cn } from "@/lib/utils";
import type { FeatureItem } from "@/lib/content";

interface FeatureListProps {
items: FeatureItem[];
className?: string;
}

export function FeatureList({ items, className }: FeatureListProps) {
return (
<ul className={cn("grid gap-4 sm:grid-cols-2", className)}>
{items.map(({ title, description, icon: Icon }) => (
<li
key={title}
className="flex gap-4 rounded-2xl border border-border/60 bg-card/80 p-5 shadow-sm transition-colors hover:border-primary/50"
>
<span className="flex h-10 w-10 items-center justify-center rounded-xl bg-primary/10 text-primary">
<Icon className="h-5 w-5" aria-hidden="true" />
</span>
<div className="space-y-1">
<h3 className="text-base font-semibold tracking-tight text-foreground">{title}</h3>
<p className="text-sm leading-relaxed text-muted-foreground">{description}</p>
</div>
</li>
))}
</ul>
);
}
23 changes: 23 additions & 0 deletions components/docs/section-heading.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
import type { HTMLAttributes, ReactNode } from "react";

import { cn } from "@/lib/utils";

interface SectionHeadingProps extends HTMLAttributes<HTMLHeadingElement> {
id: string;
children: ReactNode;
}

export function SectionHeading({ id, className, children, ...props }: SectionHeadingProps) {
return (
<h2
id={id}
className={cn(
"scroll-mt-28 text-3xl font-semibold tracking-tight text-foreground",
className,
)}
{...props}
>
{children}
</h2>
);
}
Loading