Contributing to Refract documentation

Documentation changes are contributions. This page covers conventions, structure, and process for improving Refract docs.

What to contribute

Contribution Example
Fix a typo or stale reference Package names, env vars, URLs
Improve a tutorial Add a real walkthrough with actual output
Add a diagram SVG diagrams in assets/
Add a new page New use case, integration guide, or reference
Improve the build system build.mjs, CSS, rendering

Repository structure

refract-docs/
├── docs/               # Markdown source (one .md per page)
│   ├── tutorials/      # Tutorial pages
│   └── ...
├── assets/             # Static assets (SVGs, CSS)
├── build.mjs           # Static site builder
├── dist/               # Built output (gitignored, CI-only)
└── package.json

Page conventions

File naming

Front matter

No YAML front matter needed. The first # Heading in the file becomes the page title. The page slug is the filename minus .md.

Tone

Code blocks

Use fenced code blocks with language tags:

\`\`\`bash
refract analyze "Earth" --depth detailed
\`\`\`

\`\`\`python
import pandas as pd
\`\`\`

Links

Use relative links to other docs pages:

[Concepts](../concepts.md)
[CLI reference](../cli.md)

External links use full URLs.

Diagrams

SVG diagrams go in assets/. Reference them with a relative path:

![Architecture data flow](architecture-flow.svg)

The build script copies assets/ into dist/ so relative paths work.

Adding a new page

  1. Create docs/<slug>.md with the page content
  2. Add the page to the NAV array in build.mjs:
    {
  title: 'Appendix',
  slug: null,
  children: [
    // ... existing entries ...
    { title: 'Your New Page', slug: 'your-new-page' },
  ],
},
  3. Run npm run build to verify
  4. Open a PR

Diagram style

All diagrams use consistent styling:

Tutorial checklist

A good tutorial:

Build and preview

npm run build        # Build static site to dist/

The site is plain HTML — open dist/index.html in a browser, or serve with any static file server:

npx serve dist

Review process