Configuration

Choose a configuration file

The CLI discovers monoline-docs.yml, monoline-docs.yaml, or monoline-docs.config.mjs in its working directory. Keep one discovery candidate, or select a file with --config. YAML is enough for ordinary sites; an .mjs file can export a configuration object as its default export.

This minimal YAML configuration expects a content/index.md beside it:

title: Team handbook
contentDirectory: ./content
outDirectory: ./dist

Directory paths loaded through the CLI or loadConfig are relative to the configuration file, not the terminal’s working directory. Unknown configuration keys fail validation, so a misspelled option does not silently do nothing.

Include existing documentation directories

Use contentMounts to publish existing local Markdown or MDX directories without copying their files into contentDirectory:

contentDirectory: ./content
contentMounts:
  - directory: ../../docs
    route: /repository

Each mount requires a local directory and a non-root route without a trailing slash. Paths are relative to the configuration file when using the CLI or loadConfig; direct build API paths follow the caller’s working directory. Routes, including explicit page slugs, are prefixed by the mount route. A top-level index.md or README.md becomes the mount’s landing page.

Mounted pages require the same title frontmatter as other pages. A leading H1 matching the frontmatter title is omitted from the mounted page’s rendered body, because the shell displays that title. This preserves the heading in repository Markdown without duplicating it on the site. Other headings remain unchanged.

Relative Markdown links resolve across published source directories. Links to repository files that are not published pages should use their GitHub URLs. Mounted pages participate in navigation, search, sitemaps and Markdown/AI exports; draft and noindex rules still apply. Preview watches edits and new pages in mounted directories. Global content.editLink applies only to the primary tree; mounted pages omit it rather than generating an incorrect relative edit path.

The builder rejects duplicate routes, repeated source files and overlap between mounted content and output directories. Repository guides show this configuration in use.

Editor completion

The package ships schema.json for YAML editors that support JSON Schema, such as the Red Hat YAML extension for VS Code. monoline-docs init adds this comment at the top of the starter configuration:

# yaml-language-server: $schema=./node_modules/@chitrank2050/monoline-docs/schema.json
title: Team handbook

Add the comment to an existing configuration to get option completion and checks for unknown keys, types and nested navigation. The path is relative to the YAML file; adjust it when your configuration is in a subdirectory. Install the package first. The local schema follows your installed package version and works offline.

The CLI remains authoritative: build validation also checks safe paths, URLs, language tags, conflicting aliases, route existence and assets. An editor check does not replace a successful production build.

Reference

Use appearance for logo and stylesheet examples and deployment for host layouts. Follow SEO and social sharing for site, base, title templates, social images and publishing checks.

Internal header and footer routes automatically include base. The edit URL receives the content-relative Markdown or MDX path:

header:
  links:
    - label: Writing
      href: /writing
footer:
  text: Released under the MIT License.
  links:
    - label: GitHub
      href: https://github.com/example/docs
content:
  editLink:
    href: https://github.com/example/docs/edit/main/content/{path}
    label: Improve this page

Shell controls

header:
  primaryAction:
    label: Get started
    href: /writing
  announcement:
    text: Documentation preview is available.
    href: /writing
sidebar:
  enabled: true
content:
  showLastUpdated: true
  copyPageLink: true

The primary action uses the same safe links as header links. An announcement can omit href to show plain text. Sidebar, last-updated and copy-link controls default to enabled. A page’s sidebar: false still hides its sidebar. Last-updated dates require updatedAt: YYYY-MM-DD frontmatter. Copy page link copies the current URL, including its fragment; it does not export Markdown.

Appearance and branding

Use appearance for defaultMode, density, radius, accent and local font declarations. branding contains logo and favicon. See Appearance for working examples.

Search, exports and integrations

search.enabled controls the search feature. seo accepts optional titleTemplate, socialImage, socialImageAlt, author and publisher. See SEO and social sharing for identity configuration and publishing checks. integrations.scripts adds explicitly authored local asset or HTTPS script URLs.

footer.showBranding defaults to true; footer text and links can be configured independently. See exports, OpenAPI, CLI and the programmatic API for their respective workflows.

Social images and scripts

Set site before configuring seo.socialImage: it supplies the origin for the absolute social image URL. The renderer includes Open Graph and Twitter titles, descriptions and sharing images. Indexable pages also emit website, page and breadcrumb structured data using the configured site URL and language. Images must be local /assets/ PNG, JPEG or WebP files, resolved from assetsDirectory. Use socialImageAlt to describe the image; it defaults to the site title. Optional author and publisher identify the actual person or organization responsible for the documentation. Their objects accept type (Person or Organization), name, and optional HTTP(S) url and sameAs profile URLs.

Author-maintained page updatedAt dates supply structured-data dateModified and sitemap lastmod. Leave dates absent when no truthful modification date is available; a build timestamp is not a content update.

site: https://docs.example.com
seo:
  titleTemplate: "%s | Team handbook"
  socialImage: /assets/social.png
  socialImageAlt: Example SDK documentation
  publisher:
    type: Organization
    name: Example SDK
    url: https://example.com
integrations:
  scripts:
    - /assets/analytics.js

Integration scripts must use local /assets/*.js files or HTTPS URLs. They load only when configured. Script code and external providers are trusted author choices; review them before adding them to your documentation site.

Legacy aliases

Top-level defaultMode, logo, headerLinks and editLink remain compatibility aliases. New sites should use appearance.defaultMode, branding.logo, header.links and content.editLink. Do not configure both forms of the same option.