Skip to content

Layout and configuration

Configure the documentation shell, center your content, and choose where the table of contents lives.

On this page

Configuration belongs to your app

Use nuxt.config.ts for modules, i18n, and build settings. Use app/app.config.ts for the documentation interface. Keep brand colors and typography in your app's CSS. Content and navigation metadata belong beside your Markdown.

All settings below are optional. Nuxt provides autocomplete for @igrislabs/indocio through the layer's app configuration.

app/app.config.ts
export default defineAppConfig({
  indocio: {
    docs: {
      content: { width: '42rem' },
      sidebar: { enabled: true, width: 240, collapsible: false },
      toc: { enabled: true, position: 'content', depth: 3 },
      breadcrumbs: true,
      footer: true,
      navigation: true,
      search: true,
      actions: { copyLink: true },
    },
    spaces: { switcher: 'dropdown' },
  },
})

The example shows the defaults. navigation controls previous/next links. sidebar.width is a number in pixels, between 180 and 480. Enable sidebar.collapsible to show a desktop toggle; the mobile drawer remains available whenever the sidebar is enabled.

Keep the article centered

content.width sets the article's maximum width. Use a positive CSS length such as 42rem, 800px, or 75ch. The article stays centered against the screen, independently of the sidebar and table of contents. It shrinks when available space is smaller than the requested maximum.

app/app.config.ts
export default defineNuxtConfig({
  extends: ['@igrislabs/indocio'],
})

content keeps the TOC beside the article. right places it against the layout's right edge. Neither option shifts the article away from the screen's center. When both columns cannot fit, the TOC becomes an expandable control above the page content.

toc.depth includes headings through that level, from 2 to 6. The content parser must also generate those headings. For example, to include levels 2–4:

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['@igrislabs/indocio'],
  content: {
    build: { markdown: { toc: { depth: 2, searchDepth: 4 } } },
  },
})

Page and product overrides

With the live customizer enabled, browser preferences preview above the settings below. Reset the preview to restore source-defined behavior.

Settings resolve from page frontmatter, then the active space's .navigation.yml, then app.config.ts, then defaults. Nested objects merge by field: changing toc.position preserves toc.enabled and toc.depth.

content/api/reference.md
---
title: API reference
docs:
  content:
    width: 60rem
  toc:
    position: right
  actions:
    copyLink: false
---

The same docs object works in a space's .navigation.yml. Invalid settings report the source and field. Unknown settings are rejected to catch spelling mistakes.

Configure an edit URL with a {path} placeholder. Indocio replaces it with the source stem and .md extension, including numbered folders and locale folders. Each segment is URL-encoded.

app/app.config.ts
export default defineAppConfig({
  indocio: {
    docs: {
      actions: {
        edit: {
          url: 'https://github.com/your-org/docs/edit/main/content/{path}',
          label: 'Improve this page',
        },
      },
    },
  },
})

Set actions.edit: false on a page or space to disable an inherited edit link.

Use the repository's actual content location in the URL, for example apps/docs/content/{path} in a workspace.

Layout CSS variables

Override these variables on .docs-layout in your application's stylesheet:

VariableDefaultPurpose
--docs-header-height3.5remHeader height and sticky offsets
--docs-toc-width13remDesktop TOC width
--docs-toc-gap6remGap beside the article in content mode

Configure sidebar and article widths through app.config.ts so geometry stays synchronized. The sidebar divider continues through the header.

Both landing and documentation headers read indocio.header.links. Groups use IPEX's sliding navigation. Internal destinations automatically follow the active locale.

app/app.config.ts
export default defineAppConfig({
  indocio: {
    header: {
      links: [
        { label: 'Guides', to: '/getting-started/introduction' },
        {
          label: 'Writing',
          children: [
            {
              label: 'Markdown tabs',
              to: '/components/tabs',
              icon: 'tabler:components',
              description: 'Write richer Markdown.',
            },
          ],
        },
      ],
    },
  },
})

Keep your header links in the consuming app. See Component overrides for custom header actions and other extension points.

Indocio · Built with Nuxt Content, IPEX, and Akaza UI.