# Choose, customize, and share a documentation theme

> Use Nibleaf themes safely across previews and published documentation, then export or import a validated, versioned theme template.

Nibleaf includes three original themes with different page structures.
**Harbor** is a classic reference shell: persistent library navigation, a reading
column, and a right-hand page outline. **Manuscript** is an editorial shell that
moves the library into a horizontal chapter deck above a focused reading column.
**Signal** is a compact technical workspace with a narrow library rail, wide
article canvas, and an inline command index above the page. Their names, tokens, layouts, and assets
are Nibleaf-owned implementations. Public documentation products informed the
general product patterns—preset galleries, semantic customization, and preview
before publish—but Nibleaf does not copy their proprietary code, assets, names,
or trade dress.

Projects created before theme schema v1 retain their existing palette and layout
until an owner selects, customizes, or imports a theme. This compatibility mode
avoids an unrequested visual change to an existing published site.

## Renderer architecture

The app resolves saved theme data once and passes it to a documentation theme
provider. The provider selects a registered React template from the structural
`layout.shell` value, while the theme preset continues to own metadata and
semantic tokens. Each registered template independently composes the published
reader, project preview, settings preview, and article/page-outline layout.
Consequently, changing a shell changes the rendered information architecture,
not merely CSS order or color. The publishing worker uses the same versioned
shell value for static exports, so exported and interactive renderers share a
stable layout contract without sharing browser-specific implementation code.

The responsive structures remain distinct. Harbor collapses its persistent
library and page outline into compact navigation around a reference article.
Manuscript preserves its masthead, horizontally scrollable chapter deck, and
paper-like reading surface before reducing to a single long-form column. Signal
keeps a compact command bar, library rail, wide code canvas, and command index,
then converts the rail into a horizontally scrollable mobile navigator. Logical
CSS properties preserve those relationships in both LTR and RTL.

## Inspiration and ownership boundary

The design process reviewed the current public docs-layout and component
inventories for [Fumadocs](https://www.fumadocs.dev/docs/ui/layouts/docs),
[Mintlify](https://mintlify.com/docs/themes), and
[ReadMe](https://docs.readme.com/main/docs/built-in-components), including
[ReadMe's AI-discovery guidance](https://docs.readme.com/main/docs/ai-discoverability).
Those
sources informed general expectations such as presets, semantic settings,
collapsible navigation, page outlines, layout choices, and a preview-first
workflow. Harbor, Manuscript, and Signal use original Nibleaf
names, token values, component treatments, code, and assets. Product names in
this paragraph belong to their respective owners and do not imply affiliation.

## Customize a draft safely

Open **Site editor → Themes**. Select a starter theme, then adjust appearance,
density, structural shell, content width, radius, header, sidebar, navigation, code, callouts,
cards, tabs, tables, and semantic light/dark colors. The preview can switch
independently between English/Arabic and light/dark modes.

The editor validates text and accent contrast before saving. **Undo** returns to
the previous edit, **Cancel changes** restores the last saved project settings,
and **Reset** restores the selected preset. These actions affect only the draft.
The current `READY` deployment remains public until the project is published
again. Preview both language directions and both color modes before publishing.

Theme components consume stable semantic variables such as
`--theme-canvas`, `--theme-foreground`, `--theme-surface`, `--theme-accent`,
`--theme-focus`, and `--theme-code`. Search uses the same interface, and future
AI surfaces can opt into it with `data-theme-surface="ai"` without depending on
the page renderer's internal structure.

The authenticated theme catalog returns stable theme/component IDs, structural
capabilities, and Paraglide message keys. Preset names, descriptions, and
rationales shown in the dashboard are localized through Paraglide rather than
taken from hard-coded repository metadata. A custom theme's exported metadata
remains repository identity, not a translated UI-copy contract. Adapters receive
this sanitized catalog through a shared action; they never receive filesystem
paths, manifests, snapshots, repository binaries, or customer page content.

## SEO and AI discovery defaults

Every theme uses the same publication rules while rendering its own structure.
Published pages emit a canonical, robots directive, Open Graph/Twitter metadata,
language alternates with `x-default`, and `TechArticle` plus breadcrumb JSON-LD.
Static archives also include `robots.txt`, `sitemap.xml`, root `llms.txt` and
`llms-full.txt`, plus scoped copies for every enabled language/version. Hidden,
private, noindex, disabled-language, and externally canonicalized pages are
excluded from discovery files. Archive URLs remain root-relative because the
portable snapshot has no trustworthy eventual host; the serving host resolves
them without inventing a domain.

## Export and inspect a template

Choose **Export** to download a canonical UTF-8 JSON file. The output is sorted
deterministically so reviews and round-trip comparisons remain useful. It
contains only theme-owned settings: theme metadata and tokens plus supported
branding and typography references. It does not contain content, credentials,
members, analytics, or executable code.

```json
{
  "kind": "nibleaf-theme",
  "version": 1,
  "metadata": {
    "name": "Product docs theme",
    "description": "Shared theme for product documentation",
    "author": "Documentation team"
  },
  "config": {
    "theme": {
      "preset": "harbor"
    },
    "styling": {
      "theme": "system"
    }
  }
}
```

Schema v1 accepts only known bounded fields. A template is limited to 128 KiB,
12 levels of nesting, and 600 traversed values. Asset references must be HTTPS
URLs or root-relative paths without traversal, credentials, or protocol-relative
hosts. Unknown fields, executable CSS/JavaScript, prototype-pollution keys, and
future schema versions fail with actionable errors. The importer migrates the
documented legacy v0 shape to v1 before validation.

## Preview and apply an import

Paste JSON or select a file, choose **Merge** or **Replace**, then preview the
exact changes. Merge updates fields supplied by the template and keeps other
theme-owned settings. Replace resets theme-owned settings first. Neither mode
changes SEO, navigation, content, analytics, access, or other project settings.

The first import request is a dry-run. Apply only after reviewing the change
list and any accessibility warnings. Applying updates the project draft; it does
not silently publish. Publish explicitly, verify the resulting deployment, and
keep the exported previous template as a rollback checkpoint.

Concurrent draft changes are protected with an optimistic compare-and-swap
update. Theme apply recomputes every theme-owned section from the latest project
configuration in one transaction, preserving sibling settings. Repeated
contention returns a conflict instead of overwriting another settings editor.

## Roll back a theme

Before a significant theme change, export the current template. To roll back,

publish a new deployment. Existing immutable deployments and previously created

settings are written.

For a full content and site archive, use [published exports](/use-nibleaf/exports).
Theme templates are small design interchange files, not project backups.

## Run and edit the Git-native repository

The repository export keeps theme/runtime/schema IDs at version 1 and requires
no migration from the existing Git-native contract. Each export is a standalone
Vite application with Paraglide, a validated vendored snapshot adapter, safe MDX
renderers, tests, and a production build. Harbor, Manuscript, and Signal ship
different customer-owned React and CSS layout files. Nibleaf-owned manifest,
snapshot, and content-map files remain the reconciliation boundary; edit theme
source and documentation content, not `.nibleaf/`.