Configuration

Lithos inherits the configuration system from Nuxt 4 and Docus, giving you fine-grained control over every aspect of your documentation site. From color schemes and typography to markdown processing and content organization, configuration files are the key to making Lithos your own. This guide covers the three main configuration files and common customization scenarios.

Nuxt Configuration Overview

The nuxt.config.ts file serves as the central hub for all Nuxt-related settings. This is where you control content processing, module registration, build options, and deployment configuration. Understanding this file unlocks Lithos's full potential while maintaining a clean separation between content and presentation.

Content Module Settings

The content module controls how Lithos discovers, parses, and processes your markdown files. The most important setting is the ignores array, which specifies files and folders that should be excluded from your documentation site. By default, Lithos ignores .obsidian, .git, .trash, .claude, and node_modules. These patterns use glob syntax, so \.obsidian matches any file or folder starting with .obsidian.

You can add custom ignore patterns to exclude specific sections of your vault. For example, if you have a Private/ folder that contains personal notes, add 'Private' to the ignores array. Alternatively, use frontmatter to control visibility on a per-file basis by setting published: false, which keeps the file in your vault but prevents it from appearing on the website.

The content module also handles file watching during development. When you save a markdown file in Obsidian, Lithos detects the change and triggers a re-compilation of that page. This hot module replacement happens in seconds, giving you near-instant feedback as you write and preview content.

Markdown Processing Pipeline

Lithos uses remark and rehype plugins to transform markdown into HTML. Remark plugins operate on the markdown syntax tree before conversion to HTML, while rehype plugins work on the HTML tree after conversion. This two-stage pipeline allows for powerful transformations while maintaining clean separation of concerns.

The remark-math plugin is configured by default to recognize LaTeX math syntax. Inline math uses single dollar signs like $E = mc^2$, while display math uses double dollar signs. The plugin converts these markers into special nodes that the rehype-katex plugin later renders as beautiful mathematical notation using KaTeX. This pipeline ensures that technical documentation with formulas looks professional without requiring manual HTML.

You can add custom remark plugins to extend markdown syntax. For example, if you want to support custom container syntax or additional markdown extensions, register them in the content.build.markdown.remarkPlugins object. Each plugin requires an instance property pointing to the imported plugin function, plus an optional options object for configuration. The same pattern applies to rehype plugins for HTML transformations.

Module Registration and Build Settings

Lithos registers several custom modules that provide Obsidian-specific features. The ~/modules/obsidian-transform module converts wikilinks to standard links and processes embeds. The ~/modules/obsidian-bases module handles database queries. The ~/modules/obsidian-graph module generates the data structure for graph visualization. These modules run during the build process, transforming your Obsidian syntax before pages reach the browser.

Third-party modules like @barzhsieh/nuxt-content-mermaid add support for Mermaid diagrams. The mermaid configuration object lets you specify themes for light and dark modes, ensuring diagrams match your site's color scheme. The @nuxt/ui module provides the component library and styling system, while nuxt-icon enables icon support using Iconify collections.

Build settings control transpilation and aliasing. Lithos transpiles the dayjs library to ensure compatibility across browsers, and creates an alias to the ESM version for optimal tree-shaking. You typically won't need to modify these settings unless you're adding new dependencies that require special handling.

App Configuration for Theme Customization

The app.config.ts file is your primary interface for visual customization. Unlike nuxt.config.ts which affects the build process, app.config.ts is runtime configuration that controls colors, fonts, component defaults, and site metadata.

Vault Theme Configuration (lithos.config.ts)

While nuxt.config.ts and app.config.ts are global to the Lithos project, you can provide vault-specific styling by placing a lithos.config.ts file in the root of your Obsidian vault. This allows each vault to have its own visual identity (fonts, colors, image filters) without modifying the core Lithos codebase.

Theme Settings

The lithos.config.ts file supports a comprehensive set of visual overrides:

• Fonts: Define custom font stacks for sans, serif, and mono typography. Lithos automatically loads Google Fonts if the "Recursive" font is detected.
• Colors: Provide a custom primary color palette (50-950 shades) and override semantic tokens for light and dark modes.
• Image Treatment: Enable specialized filters like "Noir" (grayscale/high contrast), "Scanlines" (retro CRT effect), and "Vignette" (darkened corners on hover).
• Typography: Adjust letter-spacing (tracking) for headings, body text, and code blocks for precise typographic control.

export default {
  site: {
    name: 'My Digital Garden',
    description: 'A personal collection of notes and ideas.'
  },
  theme: {
    fonts: {
      sans: "'Inter', sans-serif",
      mono: "'Fira Code', monospace"
    },
    colors: {
      primary: {
        50: '#f0f9ff',
        // ... (full 50-950 palette)
        950: '#082f49'
      }
    },
    images: {
      noir: { enabled: true, hoverRestore: true },
      scanlines: { enabled: true, opacity: 0.05 }
    }
  }
}

This per-vault configuration is particularly useful if you manage multiple vaults with different themes using a single Lithos installation. It ensures your branding travels with your content.

Color Scheme and Branding

Lithos uses Nuxt UI's color system, which is based on Tailwind CSS with semantic color tokens. The ui.colors object defines two key colors: primary and neutral. The primary color appears in links, buttons, navigation highlights, and interactive elements. The neutral color defines the grayscale palette used for text, borders, and backgrounds.

By default, Lithos uses violet as the primary color, creating a purple-tinted aesthetic that feels modern and approachable. The violet primary maps to a specific HSL range that works well in both light and dark modes, with automatic adjustments to ensure sufficient contrast. You can change the primary to any Tailwind color name like blue, emerald, rose, or amber to match your brand.

The neutral color defaults to zinc, which provides a warm gray that's easier on the eyes than pure black-and-white. Zinc has a subtle brown undertone that feels more natural than cooler grays. Alternatives include slate (cool gray), gray (true neutral), or stone (warm gray). This choice significantly affects the overall feel of your site, so experiment to find what suits your content.

Component Style Overrides

The ui object allows overriding default styles for any Nuxt UI component. Component overrides use a slots system where you target specific parts of the component structure. For example, the button component's base slot controls fundamental styling like font weight and padding, while the color slot defines color-specific styles.

Lithos includes custom overrides for several components. The command palette's itemLabelHighlight slot ensures search term highlighting uses the primary color for consistency. The content navigation component uses the link variant instead of the default pill variant, creating a cleaner sidebar without full-width background highlights on active items.

Container padding is configured through the container.base slot, which uses Tailwind's responsive utilities. The default px-4 sm:px-6 lg:px-4 provides comfortable padding on mobile while minimizing wasted space on desktop where sidebars provide natural margins. The page body's base slot removes excessive bottom padding that creates too much whitespace on short pages.

Layout and Grid Configuration

The page component configuration defines the three-column layout structure used throughout Lithos. The grid uses Tailwind's 10-column system with lg:grid-cols-10, where the left sidebar spans 2 columns, the main content area spans 7 columns, and the right sidebar (table of contents) spans 3 columns when present. On mobile, the grid collapses to a single column with logical ordering.

Compound variants handle layouts where one sidebar is missing. If only the left sidebar is present (no table of contents), the center content area expands to 8 columns. This responsive system ensures content remains readable and well-proportioned regardless of page structure.

The order-first lg:order-last utility on the right sidebar ensures the table of contents appears at the top on mobile devices, making it easy for readers to scan the page structure before diving into content. On larger screens, it moves to its natural position on the right side.

Content Configuration and Collection Setup

While Lithos doesn't require a separate content.config.ts file by default, you can create one to define Zod schemas that validate frontmatter and enforce content structure. This is particularly useful for teams or large documentation projects where consistency matters.

Defining Content Collections

Content collections group related documents and apply validation rules. For example, you might define a "guides" collection for tutorial content and a "reference" collection for API documentation. Each collection specifies required and optional frontmatter fields, their types, and default values.

A typical collection schema uses Zod's validation library. Define a schema like z.object({ title: z.string(), description: z.string(), tags: z.array(z.string()).optional() }) to ensure every guide has a title and description, with optional tags. Lithos validates frontmatter against this schema during build, catching errors before deployment.

Collections can define default values for missing fields. If every guide should have a specific icon but you don't want to repeat it in frontmatter, set a default in the schema. This reduces boilerplate while maintaining consistency across the site.

Frontmatter Validation

Zod schemas provide helpful error messages when frontmatter doesn't match expectations. If a page is missing a required field or uses the wrong type (string instead of array), the build fails with a clear error indicating which file and field caused the problem. This immediate feedback prevents broken pages from reaching production.

Custom validation rules can enforce business logic. For example, require that blog posts have both a date and an author field, or ensure that tutorial pages include a difficulty rating. These constraints codify content guidelines and make them enforceable through tooling rather than documentation.

Schema inference means your IDE can provide autocomplete and type checking when editing frontmatter. If you're using TypeScript-aware editors like VS Code, you'll get suggestions for field names and value types as you write YAML, reducing typos and speeding up content creation.

Vault Setup and Symlink Strategy

Connecting your Obsidian vault to Lithos requires understanding the symlink approach and how Nuxt's content module discovers files. This architecture keeps your vault as the single source of truth while allowing Lithos to process and publish it.

Creating and Managing Symlinks

A symbolic link (symlink) is a special file that points to another location in the filesystem. When Lithos reads the content/ directory, it follows the symlink to your actual vault without copying files. This means changes in Obsidian appear instantly in Lithos without manual synchronization.

On Unix-like systems (macOS, Linux), create a symlink with ln -s /absolute/path/to/vault content. The path must be absolute, not relative, to ensure the link works regardless of your current directory. Verify the link with ls -la content, which should show the symlink and its target path.

Windows users should use mklink /D content C:\Absolute\Path\To\Vault from an administrator command prompt. The /D flag creates a directory junction, which behaves like a Unix symlink for folders. Alternatively, WSL (Windows Subsystem for Linux) provides native symlink support and behaves identically to Unix systems.

Handling .obsidian and Hidden Folders

Your vault's .obsidian folder contains workspace settings, plugin configuration, and cache files that are irrelevant to published documentation. Lithos's default ignore patterns exclude this folder automatically, so you never have to worry about workspace preferences or plugin data leaking into the public site.

Other hidden folders like .git (if you version control your vault) and .trash (Obsidian's trash folder) are similarly ignored. This automatic filtering ensures only intentional content is published, not metadata or temporary files.

If you use additional hidden folders for private notes or working drafts, add them to the content.ignores array in nuxt.config.ts. The ignore patterns support wildcards, so you can exclude entire categories of files with patterns like **/private/** to ignore any folder named "private" at any nesting level.

Theme Customization Deep Dive

Beyond basic color changes, Lithos supports extensive theme customization through CSS variables, custom fonts, and component overrides. These techniques let you match corporate branding or create a unique visual identity.

CSS Variables and Custom Styles

Lithos loads two custom CSS files: ~/assets/css/main.css and ~/assets/css/obsidian.css. The main stylesheet defines CSS custom properties (variables) that control colors, spacing, and typography throughout the site. Override these variables to make sweeping changes without touching component styles.

For example, the --color-primary-500 variable defines the primary color's mid-tone, which CSS automatically derives lighter and darker shades from. Set this variable to your brand color, and links, buttons, and highlights update automatically. The same principle applies to font families, border radii, and shadows.

The obsidian.css file contains styles specific to Obsidian syntax elements like callouts and embeds. These styles mimic Obsidian's visual language, creating familiarity for readers who use Obsidian themselves. You can modify these styles to match your site's aesthetic while preserving the semantic structure.

Typography and Font Configuration

Lithos inherits Docus's font stack, which prioritizes system fonts for optimal performance and native feel. The default sans-serif stack includes Inter, SF Pro, Segoe UI, and Roboto, ensuring the site looks appropriate on any platform without loading custom fonts.

If you want to use custom web fonts, add them via nuxt.config.ts's app.head configuration. Use Google Fonts, Adobe Fonts, or self-hosted fonts by adding appropriate <link> tags or @font-face rules. Then override the CSS variable --font-sans in your main.css to apply the custom font throughout the site.

Monospace fonts for code blocks default to a stack including Fira Code, Cascadia Code, and Consolas. These fonts support ligatures and have excellent readability for code. Override --font-mono to use a different coding font if you have strong preferences or brand requirements.

Dark Mode and Color Adaptation

Lithos fully supports dark mode using Tailwind's dark: variant system. Every component automatically adapts to the color mode, ensuring readability and aesthetic consistency regardless of user preference. The mode switcher in the navigation bar lets readers toggle between light and dark modes, with their choice persisted across sessions.

Custom colors and overrides should include dark mode variants to maintain quality. When defining a custom component style, use dark:bg-zinc-800 alongside bg-zinc-100 to specify both light and dark backgrounds. The Tailwind color scales make this straightforward, as each color has 10 shades from 50 (lightest) to 950 (darkest).

Syntax highlighting in code blocks uses theme-aware color schemes. Mermaid diagrams respect the color mode setting, switching between light and dark diagram themes automatically. Math formulas rendered by KaTeX adjust their colors to ensure sufficient contrast in both modes.

Content Processing and Remark Plugins

Advanced users can extend Lithos's markdown processing by adding custom remark plugins. These plugins can implement new syntax, transform existing content, or inject dynamic data during the build process.

Understanding the Plugin Pipeline

Remark plugins receive an abstract syntax tree (AST) representing the markdown structure. You can traverse this tree, find specific node types, and modify or replace them. For example, a plugin might find all links pointing to external domains and add an icon indicating they leave the site.

The plugin registration in nuxt.config.ts requires an instance property containing the plugin function and an optional options object for configuration. Plugins run in order, so later plugins see the transformations made by earlier ones. Place plugins that add new syntax early in the chain, and plugins that clean up or optimize content later.

Lithos's obsidian-transform module itself operates as a set of remark plugins. It walks the syntax tree looking for wikilink nodes (created by @portaljs/remark-wiki-link), resolves their targets, and converts them to standard link nodes. This approach keeps the transformation logic separate from core Nuxt Content, making it easy to maintain and update.

Daily Notes and Special Folders

If you use daily notes in Obsidian, you might want special handling for chronological content. Lithos can treat daily notes as blog posts, generating date-based URLs and RSS feeds. Configure the daily notes folder in your frontmatter or use a custom remark plugin to detect date patterns in filenames.

The daily notes pattern typically places files in a folder like Daily/ with names like 2026-01-27.md. A custom plugin can parse these filenames, extract dates, and inject them into frontmatter. Then you can create a blog index page that lists notes chronologically, with links to each day's entry.

RSS feed generation works through Nuxt Content's built-in feed support. Define a feed configuration in nuxt.config.ts that queries all daily notes, sorts them by date, and outputs an RSS XML file. This allows readers to subscribe to your daily notes as a blog feed, receiving updates whenever you publish new entries.