Content Directory

Grafos reads all content from markdown files on disk. There is no database and no CMS. This guide explains how to organize your files, what frontmatter fields are available, and how file names map to URLs.

Directory Structure

By default, Grafos looks for content in a content/ directory at your project root. You can change this path in configuration:

content: {
  directory: 'content',
}

A typical content directory looks like this:

content/
  index.md          -> /
  getting-started.md -> /getting-started
  configuration.md  -> /configuration
  guides/
    advanced.md     -> /guides/advanced
    deployment.md   -> /guides/deployment
  reference/
    api.md          -> /reference/api
    cli.md          -> /reference/cli

The index.md file in the root of the content directory becomes the home page at /. Every other file's URL is derived from its path relative to the content directory.

File Naming

File names become URL slugs. Grafos applies the following rules:

The .md extension is stripped
Spaces are converted to hyphens
Names are lowercased for URL consistency
index.md inside a folder becomes the folder's root page

For example:

File path	URL slug
`content/index.md`	`/`
`content/my-page.md`	`/my-page`
`content/guides/index.md`	`/guides`
`content/guides/deploy.md`	`/guides/deploy`

When using wikilinks to link between pages, use the slug without the extension: [[my-page]], [[guides/deploy]].

URL slugs are used in wikilinks, graph labels, and the sidebar. Shorter file names make all of these more readable.

Frontmatter

Every markdown file should start with YAML frontmatter delimited by ---. Grafos uses the frontmatter for page titles, SEO metadata, graph labels, search indexing, and tag-based filtering.

The full frontmatter schema:

---
title: Page Title              # Required. Used everywhere: sidebar, graph, search, browser tab.
description: A short summary   # SEO meta description. Falls back to first paragraph if omitted.
tags: [tag-one, tag-two]       # Array of tags for filtering and graph coloring.
date: 2025-01-15               # ISO date string. Used for sorting and display.
updated: 2025-02-20            # Last updated date. Shown on the page if present.
draft: true                    # If true, excluded from production builds.
aliases: [alt-name, old-slug]  # Alternative names that resolve wikilinks to this page.
graph:
  exclude: false               # If true, this page is hidden from the graph.
  color: '#ef4444'             # Override the default node color for this page.
---

Only title is required. All other fields are optional and have sensible defaults.

The aliases field is particularly useful for wikilinks. If a page has aliases: [config], then [[config]] will resolve to that page even though the file is named configuration.md.

Nested Folders

Folders inside the content directory create nested URL paths and appear as collapsible groups in the sidebar explorer.

content/
  guides/
    index.md          # /guides — the section landing page
    installation.md   # /guides/installation
    deployment.md     # /guides/deployment
  reference/
    api.md            # /reference/api
    config.md         # /reference/config

A folder with an index.md gets a clickable header in the sidebar. Without an index.md, the folder is still shown as a group but the header is not a link.

The file tree that powers the sidebar is generated during the pre-build step and written to .grafos/file-tree.json. It preserves the folder hierarchy and sorts files alphabetically within each level.

You do not need folders at all. A flat content/ directory with all files at the root level works perfectly for smaller sites. Use folders when your content naturally groups into sections.

Grafos resolves wikilinks across folders. A page at content/guides/deploy.md can link to [[configuration]] and it will resolve to content/configuration.md regardless of the folder difference. If two files have the same name in different folders, use the full path: [[guides/deploy]].