@ksvedal/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 @ksvedal/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 '@ksvedal/docs/styles.css';

Basic usage

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

import '@ksvedal/docs/styles.css';
import { DocsPage } from '@ksvedal/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 '@ksvedal/docs/styles.css';
import { DocsPage } from '@ksvedal/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.',
      ]}
    />
  );
}

Render a single document

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

import '@ksvedal/docs/styles.css';
import { Docs } from '@ksvedal/docs';

export function FaqPage() {
  return <Docs docPath="nb/start/faq" />;
}

Build and publish

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

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.