@digdir/kut-docs

React components for browsing and rendering the bundled KUT documentation.

Modifying the documentation

Modify the documentation as markdown within the docs-folder and create a pull request. When merged to main, a job will index for search, create breadcrumbs, and make another pull request.

The level 1 heading (# in markdown) will be the title of the page (that shows up in navigation and search). Only use this once per document. The path of the documentation will be the path in breadcrumbs and what will have to be provided if you want to navigate directly to a page.

Install

npm install @digdir/kut-docs react react-dom @navikt/aksel-icons

@navikt/aksel-icons is a peer dependency and must be installed by the consuming app.

The host app is expected to load the design system styles it already uses before rendering these components. Import the package stylesheet in the host app so production builds do not depend on runtime style injection.

import '@digdir/kut-docs/styles.css';

Basic usage

DocsPage is the simplest way to render the bundled docs with search, breadcrumbs and navigation.

import '@digdir/kut-docs/styles.css';
import { DocsPage } from '@digdir/kut-docs';

export function App() {
  return <DocsPage />;
}

Controlled navigation

Use the controlled API if your app wants to keep the current docs path in state or sync it with a router. DocsPage can normalize either full docs paths (/nb/start/oidc/pkce) or short refs (oidc/pkce, docs/oidc/pkce, pkce.md). If you provide lang, short refs are resolved under that language.

import { useState } from 'react';
import '@digdir/kut-docs/styles.css';
import { DocsPage } from '@digdir/kut-docs';

export function DocsScreen() {
  const [path, setPath] = useState('oidc/pkce');

  return (
    <DocsPage
      lang="nb"
      currentPath={path}
      onNavigate={setPath}
      editable
      startPageHeader="Kom i gang"
      startPageParagraphs={[
        'Velg et tema for å åpne dokumentasjon.',
        'Du kan også bruke søket for å hoppe direkte til en side.',
      ]}
    />
  );
}

Start pages

Provide your own markdown files with startPages. They are listed as cards under the "Start" heading on the language landing page and open as regular pages when clicked. The heading is hidden when no start pages are provided.

Each start page has a path and the markdown content per language. The path is shared between languages and becomes the page's location (/{lang}/start/{path}), so switching language keeps the same page open. A page is only shown for the languages it has content for.

The title of each page is the level 1 heading of its content. Start pages are not part of the bundled docs, so they are not indexed or searchable. Import the files as raw strings (Vite shown here).

import '@digdir/kut-docs/styles.css';
import { DocsPage } from '@digdir/kut-docs';
import faqNb from './faq.nb.md?raw';
import faqEn from './faq.en.md?raw';

export function App() {
  return <DocsPage startPages={[{ path: 'faq', content: { nb: faqNb, en: faqEn } }]} />;
}

Search index

The search index used by DocsPage is also published as @digdir/kut-docs/search-index.json: an array of DocsSearchEntry (id, title, content, lang, path). It contains the full content of every page, so load it lazily instead of bundling it with your main chunk. Every path (e.g. /nb/start/oidc/pkce) can be passed to DocsPage as currentPath or onNavigate.

import { useEffect, useState } from 'react';
import '@digdir/kut-docs/styles.css';
import { DocsPage, DocsSearch, type DocsSearchEntry } from '@digdir/kut-docs';

export function CustomSearch() {
  const [index, setIndex] = useState<DocsSearchEntry[]>([]);
  const [path, setPath] = useState('/nb/start');

  useEffect(() => {
    import('@digdir/kut-docs/search-index.json').then((module) => {
      setIndex(module.default as DocsSearchEntry[]);
    });
  }, []);

  return (
    <>
      <DocsSearch index={index} lang="nb" onSelectPath={setPath} />
      <DocsPage lang="nb" currentPath={path} onNavigate={setPath} />
    </>
  );
}

Your bundler needs JSON module support (built in for Vite and webpack). With tsc, enable resolveJsonModule.

Render a single document

Use Docs if you only need the markdown renderer for one known document.

import '@digdir/kut-docs/styles.css';
import { Docs } from '@digdir/kut-docs';

export function PkcePage() {
  return <Docs docPath="nb/start/oidc/pkce" />;
}

Build and publish

Publishing is automated: bumping the version field in package.json and merging/pushing that change to main triggers a GitHub Actions workflow that builds and publishes the package to npm. No manual npm publish is needed for normal releases.

npm run build regenerates dist/search-index.json and then runs npm run check:dist, which fails if the index is missing, empty, or contains a path that DocsPage cannot open. prepack runs the build, so npm pack and npm publish always ship a fresh index.

To test a build locally without publishing:

npm run typecheck
npm run build
npm pack --dry-run

The package publishes the dist folder only, and scoped publishes are configured as public.

Local development

Use the built-in Vite playground to test the component in this repo while developing.

npm run dev

That opens a local page where you can switch between DocsPage and Docs, change paths, and verify navigation and rendering against the bundled docs content.

If you update dependencies, the quickest sanity-check loop is:

npm run check
npm run dev

npm run check verifies that TypeScript still passes and the package still builds to dist.