Quick Start | Grafos

Scaffold a Grafos project with the CLI, add your first content, and start the dev server.

This guide walks you through creating a Grafos site from scratch using the CLI, adding content, and starting the development server. By the end, you will have a running wiki with a 3D graph.

Scaffold a Project

The fastest way to start is with create-grafos, which scaffolds a complete project with sensible defaults and example content:

pnpm create grafos my-wiki

The CLI will prompt you for:

Project name — used in package.json and the default site title
Description — a short description for your site
Features — which features to enable (graph, search, backlinks, etc.)

Once complete, install dependencies and enter the project:

cd my-wiki
pnpm install

The scaffolded project includes:

A grafos.config.ts with your chosen settings
A content/ directory with example pages
A Next.js App Router layout with Grafos components wired up
Tailwind CSS v4 configured with the Grafos preset

If you already have a Next.js project, skip the CLI and follow the installation guide to add Grafos as a dependency.

Add Content

Content in Grafos is plain markdown. Create files in the content/ directory and they become pages on your site. The filename (without .md) becomes the URL slug.

Create a new page at content/hello.md:

---
title: Hello World
description: My first Grafos page
tags: [example, hello]
---

# Hello World

This is my first page. I can link to other pages with [[index|wikilinks]].

> [!note] Callouts work too
> Grafos supports Obsidian-style callouts out of the box.

Frontmatter

Every content page should have YAML frontmatter at the top of the file. The frontmatter provides metadata that Grafos uses for the page title, SEO, graph labels, search indexing, and tag filtering.

The supported frontmatter fields are:

---
title: Page Title           # Required. Used in the sidebar, graph, and browser tab.
description: A short summary # Used for SEO meta tags and search result previews.
tags: [tag-one, tag-two]    # Used for filtering and graph coloring.
date: 2025-01-15            # Optional. Used for sorting and display.
draft: true                 # Optional. Excludes the page from production builds.
---

The title field is the only required field. If description is omitted, Grafos will extract the first paragraph of content as a fallback. If tags is omitted, the page will have no tags.

Pages with draft: true are excluded from the production build, the search index, and the graph. They are still visible during development so you can preview them.

See content-directory for more details on file organization and frontmatter options.

Start Development

Start the development server:

pnpm dev

This runs the Grafos pre-build step (scanning content and generating cache artifacts) followed by the Next.js dev server. Open http://localhost:3000 to see your site.

During development, Grafos watches your content/ directory for changes. When you add, edit, or delete a markdown file:

The manifest is updated with new metadata
The graph is recalculated with new links
The search index is rebuilt
The sidebar file tree is refreshed

Changes appear in the browser without a full page reload.

To build for production:

pnpm build

To preview the production build locally:

pnpm start

From here, explore the configuration guide to customize your site, or dive into the feature guides for the graph, search, and wikilinks systems.