Migrating existing docs

If you already have a docs/ folder — a docs.json nav config, .mdx pages, an images/ folder — it works with Huell with no restructuring. Connect the repo, or zip the docs/ folder and upload it.

Supported docs.json fields

navigationobject

Flat (navigation.groups), grouped, or tabbed (navigation.tabs) — all three shapes are read directly. Tabs become top-level sidebar sections.

colors.primarystring

Used as the site’s accent color, derived into a full light/dark scale automatically.

navbar.linksarray

Rendered as plain links in the top navbar.

navbar.primaryobject

Rendered as a highlighted button in the top navbar (commonly a GitHub link).

logostring | object

Either a single path (e.g. "/logo/mark.svg"), or {light, dark} for theme-specific variants. Shown top-left on every page, replacing the site title text. The file must live under an images/, logo/, or assets/ folder (or loose at the docs root) alongside docs.json — those are the only paths copied into the built site. Falls back to Huell’s own default mark if unset.

faviconstring

A path (e.g. "/favicon.svg"), same file-location rule as logo. Defaults to /favicon.svg if a file with that exact name exists at the docs root, even with this field unset.

background.color.lightstring

Override the page/nav/sidebar background for light mode — the whole shell reads as one flat color, rather than just the page background changing on its own.

background.color.darkstring

Same, for dark mode.

Callouts and components

These content components are available in every page without an import — write them exactly as you already have them:

Note, Info, Tip, Check, Warning, Danger, Card, CardGroup, Tabs, Tab, Steps, Step, CodeGroup, Expandable, ParamField, ResponseField.

Tip

Frontmatter (title, description) is copied as-is. A page with no title gets one defaulted from its filename, and a warning is logged so you know it happened.

LaTeX math

$$...$$ block math is supported and renders with proper typesetting — no configuration needed.

Known gaps

Caution

CodeGroup renders its child code blocks stacked, not as switchable tabs — the multi-language code examples all show, just not with a tab switcher yet.

Caution

An OpenAPI spec (api.openapi) is copied into the built site as a static file, not turned into generated API reference pages.

If your docs use a component outside the list above, the build fails on that page rather than silently dropping content. The failure is recorded on the build, though there’s no dashboard view for the log yet — check it directly on the builds table in the database in the meantime.