npm package: @ksvedal/docs
Description: React components for browsing and rendering bundled KUT documentation.
Author: Team Kundetjenester
Latest version: 0.2.1

# `@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

```bash
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.

```tsx
import '@ksvedal/docs/styles.css';
```

## Basic usage

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

```tsx
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.

```tsx
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.

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

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

## Build and publish

```bash
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.

```bash
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:

```bash
npm run check
npm run dev
```

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