Dewey’s primary product surface is the CLI: dewey init, build and check (see CLI Reference). The TypeScript API supports typed configuration for the frozen 0.4 pipeline, programmatic artifact retrieval, theme CSS, prompt templates, and an optional React presentation layer. The public module is defined by packages/docs/src/index.ts; package subpaths are defined by packages/docs/package.json.
Choose the right surface
| Goal | Surface | Import or command |
|---|---|---|
| Set up docs, front door and site | CLI | bunx dewey init |
Build the site, llms.txt, .md copies and llms-full.txt | CLI | bunx dewey build |
| Check maps, reviews, references and outputs | CLI | bunx dewey check |
| Collect or build 0.4 retrieval artifacts in code | Artifact subpath | @deweydocs/dewey/agent-artifacts |
| Render Markdown in an existing React app | Optional UI | @deweydocs/dewey + CSS subpaths |
| Style a site with a house skin | CSS subpath | @deweydocs/dewey/css/skins/<name>.css |
Type-check a dewey.config.ts for the frozen commands | Main TypeScript module | @deweydocs/dewey |
The React components render Markdown for people inside an app you already have. They do not replace dewey build, which writes its own static site.
Package entry points
| Package path | Contents |
|---|---|
@deweydocs/dewey | Configuration helper, themes, React components, hooks, skills, utilities, and types |
@deweydocs/dewey/react | Compatibility alias for the same module as @deweydocs/dewey |
@deweydocs/dewey/agent-artifacts | Markdown collection, manifests, bundles, and ownership-safe artifact writing |
@deweydocs/dewey/css | Full CSS bundle |
@deweydocs/dewey/styles | Alias for the full CSS bundle |
@deweydocs/dewey/css/base.css | Base component styles |
@deweydocs/dewey/css/tokens | Semantic --dw-* tokens |
@deweydocs/dewey/css/tailwind | Tailwind-oriented CSS |
@deweydocs/dewey/css/colors/<theme>.css | One published color preset |
@deweydocs/dewey/css/skins/<name>.css | One site skin: dewey, openscout, talkie, lattices, hudsonkit, atlas, endpoint, terminal |
@deweydocs/dewey/tailwind | Tailwind preset module |
There is no wildcard color export. <theme> must be one of the fourteen published names listed under Themes.
Configuration API
defineConfig parses and returns a DeweyConfig; it is not just a TypeScript identity helper. dewey.config.ts is read only by the frozen commands (audit, generate, agent, create, update, eject); init, build and check use .dewey/project.json instead. Invalid values throw a Zod validation error. Its source is packages/docs/src/cli/schema.ts.
// dewey.config.tsimport { defineConfig } from '@deweydocs/dewey'export default defineConfig({ project: { name: 'my-library', tagline: 'A useful TypeScript library', type: 'npm-package', version: '1.0.0', }, agent: { criticalContext: ['Use Bun for package operations'], entryPoints: { API: 'src/index.ts', Tests: 'test/' }, rules: [ { pattern: '*.test.ts', instruction: 'Use bun:test.' }, ], sections: [], // empty means all human-readable docs }, docs: { path: './docs', output: './', required: ['overview', 'quickstart', 'api'], }, install: { objective: 'Install my-library.', prerequisites: ['Node.js 18+'], steps: [{ description: 'Install', command: 'bun add my-library' }], doneWhen: { command: 'bun test', expectedOutput: 'all tests pass' }, },})DeweyConfig
| Field | Type | Default / requirement |
|---|---|---|
project.name | string | Required |
project.tagline | string | Optional |
project.type | ProjectType | 'generic' |
project.version | string | Optional |
agent.criticalContext | string[] | [] |
agent.entryPoints | Record<string, string> | {} |
agent.rules | { pattern: string; instruction: string }[] | [] |
agent.sections | string[] | []; empty includes every human-readable document |
docs.path | string | './docs' |
docs.output | string | './' |
docs.required | string[] | ['overview', 'quickstart'] |
install.objective | string | Optional |
install.doneWhen | { command: string; expectedOutput?: string } | Optional |
install.prerequisites | string[] | [] |
install.steps | Install step array | [] |
install.hostedUrl | string | Optional |
ProjectType is 'macos-app' | 'npm-package' | 'cli-tool' | 'react-library' | 'monorepo' | 'generic'.
Programmatic agent artifacts
Import this surface from @deweydocs/dewey/agent-artifacts, implemented in packages/docs/src/cli/agent-artifacts.ts.
import { buildAgentManifest, collectMarkdownArtifacts, getMarkdownArtifact, writeAgentArtifacts,} from '@deweydocs/dewey/agent-artifacts'const options = { rootDir: process.cwd(), docsDir: './docs',}const project = { name: 'my-library', version: '1.0.0' }const docs = await collectMarkdownArtifacts(options)const manifest = buildAgentManifest(docs, { project })const api = await getMarkdownArtifact('api', options)const preview = await writeAgentArtifacts({ ...options, outputDir: './generated', project, dryRun: true,})console.log(manifest.recommendedReadOrder, api?.rawUrl, preview.operations)dryRun: true plans the same ownership-aware operations without writing. A real write creates or updates Dewey-owned outputs and prunes stale outputs in the selected artifact scope; overwrite: true explicitly permits replacement of reviewed desired-output conflicts, including modified or unowned targets.
Artifact functions
| Export | Signature / result |
|---|---|
collectMarkdownArtifacts(options?) | Recursively parse .md and .mdx; returns sorted Promise<MarkdownArtifact[]> |
getMarkdownArtifact(slug, options?) | Find by normalized slug or source path; returns Promise<MarkdownArtifact | null> |
getPromptArtifact(promptId, options?) | Find a prompt under prompts/; returns Promise<MarkdownArtifact | null> |
parseDocArtifact(filePath, raw?, options?) | Parse one file or supplied Markdown string into a MarkdownArtifact |
buildAgentManifest(docs, options?) | Build an AgentManifest; includeContent controls embedded Markdown/content |
buildPromptRegistry(docs, options?) | Build the schema-versioned prompt registry |
buildContextBundle(docs, slugs, title?) | Render selected slugs as one Markdown bundle |
buildAgentArtifactFiles(options?) | Build generated file descriptions in memory without applying them |
writeAgentArtifacts(options?) | Plan and optionally apply artifact writes; returns counts, paths, and operations |
Artifact types and classification
CollectMarkdownArtifactsOptions accepts rootDir? and docsDir?. WriteAgentArtifactsOptions adds outputDir?, project?, dryRun?, and overwrite?. AgentArtifactsProject is { name: string; version?: string; tagline?: string; repository?: string }.
MarkdownArtifactKind is 'doc' | 'agent' | 'prompt' | 'reference' | 'proposal'. Classification is path-based:
| Path pattern | Kind |
|---|---|
prompts/** | prompt |
agent/** or a slug ending in .agent | agent |
reference/** | reference |
proposals/** | proposal |
| Everything else | doc |
A MarkdownArtifact includes id, slug, kind, optional promptId, title/description, sourcePath, retrieval URLs, frontmatter, headings, token estimate, raw Markdown, and body content. Manifest types exported by the subpath are AgentManifest, AgentManifestEntry, PromptManifestEntry, MarkdownArtifact, MarkdownHeading, and the option/project types above.
React API
React is an optional presentation layer. The main source is packages/docs/src/index.ts; component contracts live in packages/docs/src/components/.
'use client'import { AutoTableOfContents, CopyButtons, DeweyProvider, MarkdownContent,} from '@deweydocs/dewey'import '@deweydocs/dewey/css/base.css'import '@deweydocs/dewey/css/tokens'import '@deweydocs/dewey/css/colors/ocean.css'export function DocPage({ markdown, agentMarkdown }: { markdown: string agentMarkdown: string}) { return ( <DeweyProvider theme="ocean"> <CopyButtons markdownContent={markdown} agentContent={agentMarkdown} /> <MarkdownContent content={markdown} /> <AutoTableOfContents markdown={markdown} /> </DeweyProvider> )}Components that call Dewey hooks must be descendants of DeweyProvider. In a Next.js App Router project, put the provider and interactive components behind a client boundary; load Markdown and generate static params on the server.
Provider and complete app
| Export | Required props | Important optional props |
|---|---|---|
DeweyProvider | children | components, theme, defaultDark, storageKey |
DocsApp | docs: Record<string, string> | config, currentPage, providerProps; onNavigate is currently reserved and not invoked |
DocsIndex | tree: PageNode[] | projectName, tagline, description, basePath, hero, showSearch, heroIcon, quickLinks, layout |
FrameworkComponents can provide a Link component accepting anchor props plus href, and an optional Image component accepting image props. ThemeConfig accepts preset?, partial colors (primary, background, foreground, accent), and partial fonts (sans, mono).
DocsAppConfig.layout.header is boolean | 'minimal'; the other layout switches are booleans: sidebar, toc, footer, prevNext, and breadcrumbs.
Layout and content components
| Export | Required props | Important optional props |
|---|---|---|
Header | None | projectName, homeUrl, backUrl, backLabel, label, showThemeToggle, actions |
Sidebar | tree | currentPage, projectName, basePath, isOpen, onClose, header, footer |
MarkdownContent | content | isDark |
TableOfContents | None | items, title, className, scrollOffset |
AutoTableOfContents | None | markdown, containerRef, title, className |
DocsLayout | children, title, navigation, projectName | Router-neutral shell; accepts currentPage and a framework LinkComponent, with plain anchors by default; its prop type is not re-exported by the main entry point |
CodeBlock / HeadingLink | See source | Values are public, but their prop interfaces are not exported |
TocItem is { id: string; title: string; level: number }. Related exports are useActiveSection, extractTocItems, extractTocFromDom, useTableOfContents, and extractSections.
Content and agent-friendly components
| Export | Required props | Important optional props / unions |
|---|---|---|
Callout | children | type?: 'info' | 'warning' | 'tip' | 'danger', title |
Tabs / Tab | children; Tab also requires label | Tabs.defaultTab |
Steps / Step | children; Step also requires title | — |
Card | title | description, icon, href, children |
CardGrid | children | columns?: 2 | 3 | 4 |
FileTree | items | defaultExpanded; item type?: 'file' | 'folder' |
ApiTable | properties | title |
Badge | children | variant, size?: 'sm' | 'md' |
CopyButtons | markdownContent | agentContent, showLabels, onCopy, className |
AgentContext | content | title, defaultExpanded, className |
PromptSlideout | isOpen, onClose, info, starterTemplate | title, description, params, examples, expectedOutput, className |
BadgeVariant is 'default' | 'success' | 'warning' | 'danger' | 'info' | 'purple'. CopyButtons.onCopy receives 'markdown' | 'agent' | 'plain'.
Navigation types
PageNode is a discriminated union of PageItem, PageFolder, and PageSeparator using type: 'page' | 'folder' | 'separator'. Page/navigation badge colors are 'info' | 'success' | 'warning' | 'error' | 'default'. NavigationConfig is NavigationGroup[].
Legacy compatibility types are also exported: NavItem, NavGroup, DocSection, BadgeColor, PageLink, and DocsConfig. The legacy BadgeColor union is 'blue' | 'emerald' | 'purple' | 'amber' | 'rose'.
Themes
The canonical registry is packages/docs/src/themes.ts.
import { THEME_REGISTRY, VALID_THEMES, isThemeName, resolveTheme, type ThemeName,} from '@deweydocs/dewey'const input = process.env.DOCS_THEMEconst theme: ThemeName = resolveTheme(input) // invalid or missing -> 'neutral'if (input && !isThemeName(input)) { console.warn(`Choose one of: ${VALID_THEMES.join(', ')}`)}console.log(THEME_REGISTRY[theme].cssFile)ThemeName and ThemePreset contain the same values:
'neutral' | 'ocean' | 'emerald' | 'purple' | 'dusk' | 'rose' | 'github' | 'warm' | 'midnight' | 'editorial' | 'mono' | 'hudson' | 'ink' | 'slate'
PUBLISHED_CSS_THEMES lists presets with CSS exports; VALID_THEMES lists presets accepted by generated sites. Every current registry entry belongs to both lists. resolveTheme falls back to 'neutral'.
All fourteen presets resolve the same semantic contract in light and dark: surfaces/foregrounds, primary/secondary/accent pairs, border/ring, info/warning/error/success pairs, code and syntax colors, sidebar/header colors, typography, radii, shadows, and motion. Runtime components and generated sites consume semantic --dw-* variables; public components do not own literal color palettes.
Contract tests verify every preset and generated-site theme in both modes, reject missing/dead tokens, require WCAG AA text pairs and visible focus, and check reduced-motion behavior. bun run --cwd packages/docs test:visual renders representative navigation, prose, controls, semantic states, code, and tables for 14 themes × light/dark and compares 28 Playwright screenshots.
Skills and structured agent content
The skill exports are LLM prompt definitions, not deterministic generators:
| Export | Type / role |
|---|---|
docsReviewAgent | Prompt set for accuracy and drift review; result type DocsReviewResult |
docsDesignCritic | Prompt set for structure/design critique; result type DocsDesignCritiqueResult |
promptSlideoutGenerator | Prompt set for authoring slideout configuration; type PromptSlideoutConfig |
installMdGenerator | Prompt set for installmd.org content; type InstallMdConfig |
improveAIPrompts | Iterative discovery/draft/review/refinement prompt set; types PromptImprovementPass and PromptQualityCriteria |
improveAIPromptsSkill is a deprecated alias of improveAIPrompts for compatibility.
Structured agent content can be assembled and rendered without the CLI:
import { agentContent, renderAgentJson, renderAgentMarkdown,} from '@deweydocs/dewey'const api = agentContent('api', 'API', 'Public package contracts') .enums('Themes', { ThemePreset: ['neutral', 'ocean'] }) .code('Import', 'ts', "import { defineConfig } from '@deweydocs/dewey'") .build()const markdown = renderAgentMarkdown(api)const json = renderAgentJson(api)The related exports are AgentContentBuilder, renderAgentPlainText, and the AgentContent, AgentSection, TableSection, EnumSection, CodeSection, TextSection, and ListSection types.
Complete main-module export inventory
The following names are re-exported from packages/docs/src/index.ts.
| Group | Runtime exports |
|---|---|
| Config | defineConfig |
| Themes | PUBLISHED_CSS_THEMES, THEME_REGISTRY, VALID_THEMES, isThemeName, resolveTheme |
| App/provider | DocsApp, DocsAppDefault, DocsIndex, DeweyProvider, useDewey, useTheme, useComponents, useLink |
| Layout/content | Header, DocsLayout, MarkdownContent, CodeBlock, HeadingLink, Sidebar, TableOfContents, AutoTableOfContents, useActiveSection, extractTocItems, extractTocFromDom |
| UI | Callout, Tabs, Tab, Steps, Step, Card, CardGrid, FileTree, ApiTable, Badge |
| Agent UI | CopyButtons, AgentContext, PromptSlideout |
| Skills | promptSlideoutGenerator, docsReviewAgent, docsDesignCritic, installMdGenerator, improveAIPrompts, improveAIPromptsSkill |
| Hooks/utilities | useDarkMode, useTableOfContents, extractSections, cn, resolveIcon, commonIcons |
| Agent content | agentContent, AgentContentBuilder, renderAgentMarkdown, renderAgentJson, renderAgentPlainText |
| Type group | Type exports |
|---|---|
| Config/themes | AgentRule, DeweyConfig, InstallConfig, ProjectType, ThemeDefinition, ThemeName, ThemePreset |
| App/provider | DocsAppProps, DocsAppConfig, DocsIndexProps, DeweyProviderProps, DeweyContextValue, ThemeConfig, FrameworkComponents |
| Components | HeaderProps, DocsLayoutProps, MarkdownContentProps, SidebarProps, AutoTocProps, TableOfContentsProps, TocItem, CalloutProps, CalloutType, TabsProps, TabProps, StepsProps, StepProps, CardProps, CardGridProps, FileTreeProps, FileTreeItem, ApiTableProps, ApiProperty, BadgeProps, BadgeVariant, CopyButtonsProps, AgentContextProps, PromptSlideoutProps, PromptParam |
| Skills/content | PromptSlideoutConfig, DocsReviewResult, DocsDesignCritiqueResult, InstallMdConfig, PromptImprovementPass, PromptQualityCriteria, AgentContent, AgentSection, TableSection, EnumSection, CodeSection, TextSection, ListSection |
| Navigation/utilities | PageTree, PageNode, PageItem, PageFolder, PageSeparator, FlatPage, NavigationConfig, NavigationGroup, NavigationItem, CommonIconName |
| Legacy | NavItem, NavGroup, DocSection, BadgeColor, PageLink, DocsConfig |
For command flags and workflows, use the CLI reference. For a complete server/client integration, use Integrate into an existing site.