Uranus Docs

Documentation portal built with Blume.

Local development

pnpm install --frozen-lockfile
pnpm dev

Open the server's root URL (normally http://localhost:4321/) for the entry page. The language-prefixed URL /en redirects to /; the documentation currently uses URLs without a language prefix.

Check the documentation and build the static site:

pnpm run doctor
pnpm test
pnpm build

The generated site is written to dist/. Serve this directory as the site root, including its index.html.

Documentation structure

Source	Route	Purpose
docs/index.mdx	/	Entry page linking to the available documentation
docs/openapi/openapi.yaml	/api-reference	Uranus API reference generated by Blume
docs/reference/index.mdx	/reference	Entry page for live reference data
docs/reference/event-types-and-genres.mdx	/reference/event-types-and-genres	Event types and genres fetched in the browser
docs/reference/license-types.mdx	/reference/license-types	Selectable license types fetched in the browser

blume.config.ts defines the content root, OpenAPI sources and navigation tabs. Each tab's path identifies its section and links to that section's entry page. The Uranus API tab uses /api-reference. The site title, Uranus Docs, links back to / from every section, so the entry page does not need its own tab.

Live reference pages

islands/EventTypeGenreLookup.tsx loads the current lookup from https://api.kulturbytes.de/api/event/type-genre-lookup on page load, language changes and Reload data. The page supports English, German and Danish names, search by name or original ID, summary counts, and types without genres. It shows loading, empty and error states, with a retry button and a 30-second timeout. Superseded requests are cancelled so a slow response cannot replace the newly selected language. API values render as text through React.

islands/LicenseTypeLookup.tsx loads the current license types from https://api.kulturbytes.de/api/choosable-license-types?lang=en, with the same language selection, reload and request handling. It displays the original API keys and localized names, plus descriptions when available. Search matches keys, names and descriptions. src/lib/license-types.ts validates the response before displaying it; src/lib/languages.ts defines the languages shared by both pages.

Blume discovers the island automatically. Its client = "load" export enables hydration on page load. The API is never fetched during the build; the site can still be deployed as static files. Python and ReportLab are not needed for these pages. Visitors need JavaScript and access to the API. A direct JSON link is available when JavaScript is disabled or the API request fails.

The public API must allow the site's origin through CORS. It currently returns Access-Control-Allow-Origin: *; requests omit credentials. A deployment with a Content Security Policy must also allow https://api.kulturbytes.de in connect-src. The live values are not part of Blume's build-time search index or Markdown exports; the page's own search filters the fetched data.

To add another live reference page:

1. Add its MDX page under docs/reference/ and link it from the reference index.
2. Add a React component under islands/, named in PascalCase, and use it in MDX as <YourComponent />. Export const client = "load" from the component.
3. Reuse src/hooks/useApiData.ts for loading, retry, timeout and cancellation. Pass the endpoint URL and a stable parser (a module-level function, or one created with useCallback when parsing depends on component state). src/lib/api.ts provides the common JSON transport and reader-facing ApiError; keep endpoint-specific validation in a separate module, as in src/lib/event-type-genre.ts.
4. Extend tests/reference-data.test.mjs with parser/transport tests and run the checks above.

Adding another documentation section

For a future Pluto image database section:

1. Create docs/pluto/index.mdx as its entry page and add further pages under docs/pluto/. Blume maps these files to /pluto and /pluto/....
2. Add { label: "Pluto", path: "/pluto" } to navigation.tabs in blume.config.ts. Blume scopes the sidebar to that section.
3. Add a card linking to /pluto in docs/index.mdx once its documentation is available. Adjust CardGroup's cols if multiple cards should appear side by side.

Additional OpenAPI specifications can be registered in openapi.sources, each with its own label and route, and linked from a matching navigation tab and the entry page.