Choose, customize, and share a documentation theme

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, Mintlify, and ReadMe, including ReadMe's AI-discovery guidance. 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.

{
  "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, import that file using Replace, review the diff, apply it to the draft, and publish a new deployment. Existing immutable deployments and previously created export artifacts remain unchanged. If an import fails validation, no project settings are written.

For a full content and site archive, use published 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/.