@nendlabs/docpage 0.1.0

package/dist/package.md

@@ -0,0 +1,142 @@
+# @nendlabs/docpage
+
+a config-first, interactive paper-style project page renderer for nendlabs.
+
+it ships fully compiled styles, so consumers only need one css import.
+
+### install
+
+use your package manager of choice:
+
+```bash
+npm install @nendlabs/docpage
+```
+
+```bash
+bun add @nendlabs/docpage
+```
+
+### quick start
+
+import the styles once near your app root:
+
+```ts
+import "@nendlabs/docpage/styles.css";
+```
+
+render a page from a typed config:
+
+```tsx
+import { DocPage, type DocPageConfig } from "@nendlabs/docpage";
+
+const CONFIG: DocPageConfig = {
+  brand: { name: "nendlabs" },
+  header: {
+    title: "a project page",
+    subtitle: "how we built it",
+  },
+  toc: [
+    { id: "abstract", label: "abstract" },
+    { id: "api", label: "api" },
+  ],
+  sections: [
+    {
+      kind: "prose",
+      id: "abstract",
+      titleBorder: true,
+      blocks: [
+        { kind: "p", text: "we start with the concept and work backward." },
+        {
+          kind: "ul",
+          items: [
+            "derive signals from raw events",
+            "compress context with retrieval",
+            "reason over multi-day windows",
+          ],
+        },
+      ],
+    },
+    {
+      kind: "api",
+      id: "api",
+      intro: "a tiny example with tabs.",
+      tabs: [
+        {
+          id: "curl",
+          language: "bash",
+          code: "curl https://example.com/v1/events",
+        },
+        {
+          id: "ts",
+          label: "typescript",
+          language: "typescript",
+          code: "client.event(\"user.login\", { userId: \"123\" })",
+        },
+      ],
+    },
+  ],
+  footer: { copyrightName: "nendlabs" },
+};
+
+export default function ProjectPage() {
+  return <DocPage config={CONFIG} />;
+}
+```
+
+### requirements
+
+- react and react-dom are peer dependencies (react 18+ recommended)
+- mdx sections require your host app to compile mdx into react components
+
+### mdx sections
+
+the renderer is config-first, but mdx is supported via `kind: "mdx"` sections.
+
+```tsx
+import type { DocPageConfig } from "@nendlabs/docpage";
+import AbstractSection from "./sections/abstract.mdx";
+
+const CONFIG: DocPageConfig = {
+  brand: { name: "nendlabs" },
+  header: { title: "mdx section example" },
+  sections: [
+    {
+      kind: "mdx",
+      id: "abstract",
+      titleBorder: true,
+      Component: AbstractSection,
+    },
+  ],
+};
+```
+
+code fences inside mdx are automatically rendered through the shared highlighted code block.
+
+### styling model
+
+consumers only need this import:
+
+```ts
+import "@nendlabs/docpage/styles.css";
+```
+
+this package compiles its own tailwind classes into the shipped css.
+
+important note about custom classes:
+
+- classes used inside this package are included in the shipped css
+- classes that only appear in your mdx or custom nodes are not guaranteed to exist
+- if you want arbitrary tailwind classes in your content, also run tailwind in the host app
+
+### config reference
+
+sections are discriminated by `kind`:
+
+- `kind: "prose"` with `blocks`
+- `kind: "api"` with `tabs`
+- `kind: "mdx"` with a compiled `Component`
+
+for the concrete shapes, see:
+
+- `src/types.ts`
+- `playground/src/logst-config.tsx`