Publish your system

Give your documentation its own name, then build a static site for your team.

Name and brand the site

looma-docs init --title "Fellowship UI" sets your site's name. To rename an existing local documentation site, edit title in looma.docs.json; the local server rebuilds the header, generated landing page and page titles with that name. You do not need to fork Looma or change component imports.

You can also supply your logo and navigation:

{
  "title": "Fellowship UI",
  "logo": {
    "light": "/assets/fellowship-light.svg",
    "dark": "/assets/fellowship-dark.svg"
  },
  "nav": [{ "label": "Our application", "href": "https://example.com" }]
}

Merge these fields into your existing configuration. Serve the logo URLs from your application's public assets, such as public/assets/. Leave logo unset for a text-only brand. To author your own introduction, set content to your Markdown directory and add its index.md; it replaces the generated landing page without replacing component reference pages.

The site name is yours. Component ownership stays accurate: built-in cards still identify @threadlabs/looma, while your discovered components identify the packageName you configure below. That is package attribution, not the name of your design system. Shared CSS and recipe filenames are configured under theme; changing a site title does not require renaming those files.

A navigation link with "position": "start" appears before the generated component and editor sections. Other links keep their order after those sections:

{ "nav": [{ "label": "Get started", "href": "/getting-started/", "position": "start" }] }

For documentation-site Markdown syntax and publishing options, see the Markupress documentation.

Build and preview

pnpm exec looma-docs build
pnpm exec looma-docs preview

build writes a static MarkupKit site to outDir, which defaults to .looma/site. Deploy that directory to your static host. preview serves the built files. All commands accept --root; dev and preview also accept --port.

Save your theme

Commit looma.docs.json, the theme recipe, and the generated CSS with your components. Add .looma/ to your ignore file. Keep handwritten CSS in a separate overrides file so saving a theme preserves it.

The local editor writes only the configured recipe and CSS inside the project. It rejects symlink paths, generated or dependency directories, cross-origin save requests and stale file revisions. A competing edit leaves your unsaved preview in place; reload and reconcile it before saving again. Examples are pre-rendered directly in the documentation page and share its styles and HTML Next runtime. Project component roots and example companions are trusted application code, so opt in only to sources you would run in your application. Example IDs and their label, trigger and command relationships are namespaced per specimen; companions can select stable authored hooks such as data-example-id. Width controls resize the inline stage; viewport media queries follow the documentation window.

The writer stages complete files, serializes saves with a project lock, and rolls back the recipe if replacing the CSS fails. If a process stops during a save or build, close the old editor before removing its .looma/theme-write.lock or .looma/docs-build.lock; restart and save the loaded recipe to regenerate a consistent pair. Change the server base, output directory or theme-file paths by restarting dev.