# Configuration

The app config keys, module options and collection options @maas/docs reads.

The layer reads three places: `docs` in `app.config.ts` names the site, `docs` in `nuxt.config.ts` steers the build, and `defineDocsCollections` says where the pages come from.

## App config

```ts [app/app.config.ts]
export default defineAppConfig({
  docs: {
    title: 'Mirror',
    titleSuffix: 'Mirror by Magic as a Service™',
    description: 'Tokens, utilities and unstyled components for Vue.',
    url: 'https://mirror.maas.engineering',
    version: '2.0.0',
    repository: 'https://github.com/magicasaservice/mirror',
    image: { src: '/og-image.jpg', alt: 'A glossy violet button' },
    previewThemes: ['mono'],
  },
})
```

::docs-table
---
columns:
  - label: Key
  - label: Type
rows:
  - items:
      - label: title
        description: The wordmark in the header, and the site name on social cards.
      - label: string
  - items:
      - label: titleSuffix
        description: Follows every page title in the browser tab. Defaults to `title`.
      - label: string
  - items:
      - label: description
        description: The description of every page that has none of its own.
      - label: string
  - items:
      - label: url
        description: The deployed origin. Canonical links and social cards are only written when it is set.
      - label: string
  - items:
      - label: version
        description: Shown beside the wordmark.
      - label: string
  - items:
      - label: repository
        description: The GitHub repository behind the header link, the license link and every “View source” link.
      - label: string
  - items:
      - label: image
        description: The social card, as a path inside `public/`.
      - label: '{ src: string, alt: string }'
  - items:
      - label: links
        description: Listed under the sidebar navigation. Yours come first, followed by the Magic as a Service™ links.
      - label: 'Array<{ label: string, href: string }>'
  - items:
      - label: previewThemes
        description: The `data-theme` values a component preview can switch to, besides the default.
      - label: Array<string>
---
::

## Module options

```ts [nuxt.config.ts]
export default defineNuxtConfig({
  extends: ['@maas/docs'],
  docs: {
    tokens: '../../.maas',
    sources: ['../../packages/components'],
    previews: ['../../packages/components/*/demo/*.vue'],
  },
})
```

::docs-table
---
columns:
  - label: Option
  - label: Type
  - label: Default
rows:
  - items:
      - label: tokens
        description: The directory `mirror tokens` and `mirror css` write to, relative to the app. The layer loads its Tailwind preset and the application, breakpoint and dark mode tokens from it.
      - label: string
      - label: The tokens @maas/docs ships with
        plaintext: true
  - items:
      - label: sources
        description: Directories Tailwind scans for class names, relative to the app. The `app` and `content` directories of every layer are scanned already.
      - label: Array<string>
      - label: '[]'
  - items:
      - label: previews
        description: Globs matching the demos [`::component-preview`](/components/component-preview) renders, relative to the app.
      - label: Array<string>
      - label: '[]'
---
::

## Collections

`defineDocsCollections` returns the three collections the layer queries: `home` for `index.md`, `docs` for every other page, and `docsRaw`, which serves each page as Markdown at `/raw/<path>.md`.

```ts [content.config.ts]
import {
  defineContentConfig,
  defineDocsCollections,
  z,
} from '@maas/docs/content'

export default defineContentConfig({
  collections: defineDocsCollections({
    source: [
      { include: '0.overview/*.md' },
      {
        cwd: '../../packages/plugins',
        include: '*/index.md',
        prefix: '/1.plugins',
      },
    ],
    schema: {
      since: z.string().optional(),
    },
  }),
})
```

::docs-table
---
columns:
  - label: Option
  - label: Type
rows:
  - items:
      - label: source
        description: Where the pages are read from. Defaults to every Markdown file in `content/` except `index.md`.
      - label: string | CollectionSource | Array<CollectionSource>
  - items:
      - label: schema
        description: Front matter fields added to the `docs` collection.
      - label: z.ZodRawShape
---
::

The `docs` collection reads these front matter fields on top of `title` and `description`.

| Field | Type | Description |
| --- | --- | --- |
| `badge` | `string` | A label beside the page’s name in the sidebar, such as `New`. |
| `pending` | `boolean` | Marks the page as documenting an interface that is not built yet. |
| `dataAttributes` | `Array` | Rows for [`::data-attributes`](/components/data-attributes). |
| `cssVariables` | `Array` | Rows for [`::css-variables`](/components/css-variables). |
| `guidelines` | `Array` | Items for [`::usage-guidelines`](/components/usage-guidelines). |