Documentation#

The documentation is written in enhanced Markdown, called MDX. It allows us to import other Markdown files along with React components and JavaScript logic.

Property usage guidance#

When documenting a customization property, explain its intended use, the preferred default, and when DNB UX approval is needed. Follow the intended use and customization guidance.

Keep the prop description and TypeScript JSDoc aligned so the same guidance appears in the Portal and editor. Identify technical customization examples clearly when they go beyond the component's intended patterns.

Properties pages that only document API parameters or translations can set hidePropertiesUsage: true in their frontmatter to omit the component customization note from the Portal and generated Markdown.

Sidebar navigation#

Navigation is defined in each MDX document, independently of its URL. There is no separate menu configuration file. Use the parent document's slug to place a page:

title: Installation
navigation:
  parent: web/get-started
  order: 1

A menu-only accordion has no content or route:

title: Get started
route: false
navigation:
  parent: web
  kind: group
  order: 1

Use kind: placeholder for disabled “To do” entries. A platform definition uses kind: platform and platform: web, ios, or android. Shared definitions have no platform parent and appear above the platform dropdown.

Use kind: heading with route: false for a plain group label whose child links stay visible. Use kind: group when the section should expand and collapse.

Use icons only for top-level shared entries and top-level entries within a platform. Nested pages and accordions should not declare an icon.

Published pages with a title must declare navigation, or explicitly use navigation.hidden: true when they should not appear in the sidebar. The navigation checks reject missing definitions and source files under the retired src/docs/uilib/ directory. New web documentation belongs in src/docs/web/, including pages brought in from older branches.

When an existing content page also has children, the accordion opens without navigating. Its content remains available as the first child. Give that child a name that describes what the page offers with navigation.pageTitle, such as “Quick start” or “Using typography”, rather than repeating the accordion name with “overview”. navigation.title can shorten the menu label without changing the page heading. Use navigation.hidden: true to keep a page out of the sidebar.

For an external resource, use a contentless MDX file with route: false and navigation.href. It renders as a link in its parent menu without creating a local page. Set navigation.dividerBefore: true to separate it from the preceding items.

Moving pages#

Use meaningful MDX filenames, not index.mdx. The home document is home.mdx with slug: /. When moving a page, retain its old URL in redirect_from:

redirect_from:
  - /web/get-started/quick-start

Aliases preserve query strings and fragments. A section definition can declare legacyPrefixes for all descendant routes, including TSX demonstration pages. legacyFragments maps old section anchors to a new page when content is split.

Handling themes#

If you need to show some documentation only for when a certain theme is selected, you can do so:

<VisibilityByTheme visible="eiendom">

## Eiendom examples

Text

<SpecialExample />

</VisibilityByTheme>

Link to a specific theme#

You can add a parameter called eufemia-theme to a url:

[Relative](/web/components/badge/demos/?eufemia-theme=sbanken)
Absolute: https://eufemia.dnb.no/web/components/badge/demos/?eufemia-theme=sbanken

It will change and set the currently used theme once the user visits the related page.

Printing#

Portal pages use the shared plain print layout, including fullscreen documentation. Navigation and editing tools are hidden, and the page path and version appear after the content.

A page that demonstrates its own print layout can set printLayout: custom in its frontmatter. It then owns paper colors, layout and footer behavior. Use this for document previews and dedicated print-style fixtures, independently of the fullscreen setting.

Page table of contents#

Portal builds a table of contents from visible documentation headings and their anchor links. Headings inside component demos are excluded. Keep headings descriptive and their anchor ids unique, including when importing MDX partials.

Pages without section headings omit the table of contents. Otherwise, the page title is included as the first link, using TableOfContent.Data's includeH1 option. It links back to the introduction and becomes current before the first section. The configured tocDepth still counts section levels below H1.

The static HTML includes the table of contents and its heading data alongside the page content. Hydration reuses that data, then tracks headings that are added, removed or changed in the browser. The mobile disclosure and desktop links are styled for the viewport before hydration.

Portal disables heading-list replacement animation with animateChanges set to false. Applications can opt in through TableOfContent.Root or TableOfContent.Data; see the extension documentation.

The skip link moves focus to the main content, including its title and tabs. On desktop, the outline follows the article in the reading and keyboard order. On mobile, the disclosure comes before the article. The outline uses the shared native scrollbar sizing. Scrolling inside an overflowing desktop outline stays within its list; a short outline allows the page to scroll.

The table of contents is sticky on wide screens and a disclosure above the content on smaller screens. On narrow screens it initially shows up to 10 links, including the page title, with a translated “Show all” button that disappears after revealing the remaining links. The component's maxVisibleItems property configures this limit. Browser find-in-page also reveals the full list when it matches a hidden link, where hidden="until-found" is supported. Its open or closed choice is stored in session storage with expandedStorageKey, so it survives page navigation, reloads and viewport changes within the same tab. The saved state is restored before first paint. It is hidden in focus mode and fullscreen pages.

Use frontmatter to adjust individual pages:

---
hideToc: true
tocDepth: 1
---

Use hideToc to hide the navigation and tocDepth to limit its visible heading levels. The default depth is two levels below the page title. A tab page inherits these settings from its parent unless it supplies its own value.

Language#

Write the documentation in American English, such as color, behavior, canceled, and customize.

Keep the original spelling in:

• Release notes and the changelog.
• URLs, file paths, and public names, such as /web/styling-and-themes/configuration/.
• Names and titles of external sources.

Translations follow their locale. See Locale support.