Configuration

Grafos is configured through a single grafos.config.ts file in your project root. The defineConfig() function provides type-safe configuration with full TypeScript autocompletion.

defineConfig()

Import defineConfig from Grafos and export a default configuration object:

import { defineConfig } from 'grafos'

export default defineConfig({
  site: {
    title: 'My Wiki',
    description: 'A personal knowledge base',
    baseUrl: 'https://wiki.example.com',
  },
})

The function validates your configuration at build time and provides IntelliSense for every option. If you pass an invalid value, TypeScript will catch it before you build.

All configuration options have sensible defaults. You only need to specify the options you want to change. The minimal configuration is just a site title:

import { defineConfig } from 'grafos'

export default defineConfig({
  site: {
    title: 'My Wiki',
  },
})

Site Metadata

The site object controls metadata used across your site:

site: {
  title: 'My Wiki',              // Displayed in the header, browser tab, and OG images
  description: 'A knowledge base', // Used in meta tags and the default OG description
  baseUrl: 'https://example.com', // Required for sitemap, OG images, and canonical URLs
  logo: '/logo.svg',              // Path to a logo image displayed in the header
  author: 'Your Name',            // Default author for meta tags
}

The baseUrl is required if you enable the sitemap or OG image features. It should be the full URL where your site is deployed, without a trailing slash.

Feature Flags

The features object lets you toggle major features on or off:

features: {
  graph: true,       // 3D interactive graph in sidebar and /graph page
  search: true,      // Full-text search with Cmd+K shortcut
  backlinks: true,   // Show pages that link to the current page
  toc: true,         // Table of contents sidebar generated from headings
  sitemap: false,    // Generate a sitemap.xml at build time
  ogImages: true,    // On-demand OG image generation via API route
}

When a feature is disabled, its code is tree-shaken from the bundle. Disabling the graph, for example, removes Three.js and d3-force-3d from the client bundle entirely.

Markdown Options

The markdown object configures the unified pipeline that processes your content:

markdown: {
  wikilinks: true,           // Enable [[wikilinks]] syntax
  callouts: true,            // Enable > [!type] callout blocks
  math: 'katex',             // Math engine: 'katex' | 'none'
  syntaxHighlight: 'shiki',  // Code highlighting: 'shiki' | 'none'
  shikiTheme: 'github-dark', // Shiki theme for code blocks
  remarkPlugins: [],         // Additional remark plugins
  rehypePlugins: [],         // Additional rehype plugins
}

You can pass custom remark and rehype plugins directly in the config, or use the plugins system for more complex extensions. The plugins array accepts the same format as unified's .use() method:

markdown: {
  remarkPlugins: [
    remarkGfm,
    [remarkCustomPlugin, { option: true }],
  ],
}

Full Reference

Here is the complete configuration object with all options and their defaults:

import { defineConfig } from 'grafos'

export default defineConfig({
  // Site metadata
  site: {
    title: 'Grafos',
    description: '',
    baseUrl: '',
    logo: '',
    author: '',
  },

  // Content directory settings
  content: {
    directory: 'content',     // Path to markdown files relative to project root
    ignorePatterns: [],       // Glob patterns for files to skip
  },

  // Feature toggles
  features: {
    graph: true,
    search: true,
    backlinks: true,
    toc: true,
    sitemap: false,
    ogImages: true,
  },

  // Theme configuration
  theme: {
    defaultMode: 'dark',     // 'dark' | 'light'
    accentColor: '#6366f1',  // Primary accent color
    fonts: {
      sans: '',              // Custom sans-serif font family
      mono: '',              // Custom monospace font family
    },
  },

  // Markdown pipeline
  markdown: {
    wikilinks: true,
    callouts: true,
    math: 'katex',
    syntaxHighlight: 'shiki',
    shikiTheme: 'github-dark',
    remarkPlugins: [],
    rehypePlugins: [],
  },

  // Graph visualization
  graph: {
    localDepth: 2,           // How many hops to show in the local graph
    nodeColor: '#6366f1',    // Default node color
    edgeColor: '#4b5563',    // Edge color
    labelSize: 12,           // Text label size in pixels
    physics: {
      charge: -120,          // Repulsion force between nodes
      linkDistance: 60,       // Target distance between linked nodes
    },
  },

  // Plugin system
  plugins: [],               // Array of GrafosPlugin objects
})

For theme customization, see theme. For plugin development, see creating-plugins. For content organization, see content-directory.