Introduction

Grafos is an open-source Next.js framework for building graph-powered wiki sites. It combines the simplicity of markdown-based content with a 3D interactive graph that turns your pages into a navigable knowledge network. If you have ever used Obsidian and wished you could publish your vault as a polished website with a force-directed graph, Grafos is the tool for that.

Overview

At its core, Grafos is a library, not a framework that owns your application. Your project is a standard Next.js app. Grafos provides the components, the markdown pipeline, the configuration system, and a Tailwind preset that you import into your own project. There is no proprietary build system, no vendor lock-in, and no magic. Anyone who knows Next.js can extend a Grafos site.

Content lives in plain markdown files inside a content/ directory. Grafos scans those files at build time and produces a set of cache artifacts: a manifest of all pages, a graph of links between them, a search index for full-text client-side search, and a file tree for the sidebar explorer. At runtime, pages are rendered through a unified pipeline (remark to rehype to React) with support for syntax highlighting via Shiki, LaTeX via KaTeX, callouts, wikilinks, and embeds.

The 3D graph is the flagship feature. It uses Three.js with React Three Fiber for rendering and d3-force-3d running in a Web Worker for physics simulation. Every page is a node. Every link between pages is an edge. The result is a living, interactive map of your knowledge base that users can rotate, zoom, and click through to navigate.

Grafos is designed for developers, researchers, writers, and anyone who organizes knowledge in interconnected documents. It works equally well as a personal wiki, a project documentation site, or a public knowledge base.

Why Grafos?

There are many static site generators and documentation frameworks available. Grafos exists because none of them combine all of the following properties:

Markdown-first with Obsidian compatibility. If you already write in Obsidian, you can drop your vault into a Grafos project and it works. Wikilinks resolve automatically. Callouts render with the same syntax. Embeds pull in content from other pages. You do not need to rewrite anything or learn a new content format.

A real 3D graph, not a novelty widget. The graph in Grafos is a first-class navigation tool. It shows how your pages connect to each other, highlights the current page, tracks which pages you have visited, and lets you click nodes to navigate. The local graph in the sidebar shows neighbors of the current page. The global graph shows your entire knowledge network. Both run at 60fps thanks to instanced rendering and Web Worker offloading.

Standard Next.js under the hood. Grafos does not replace Next.js or wrap it in an abstraction layer. Your project uses the Next.js App Router directly. You can add API routes, middleware, server components, or any other Next.js feature alongside Grafos. When Next.js releases a new feature, you can use it immediately without waiting for Grafos to catch up.

Config-driven feature toggling. Every major feature in Grafos can be turned on or off from a single configuration file. Want search but not the graph? Set graph: false. Want backlinks but not the table of contents? Set toc: false. You never need to dig into component code to hide something.

No database, no CMS. All content comes from markdown files on disk. There is no database to provision, no CMS to configure, no API keys to manage. Your content lives in your git repository alongside your code, versioned and portable.

Extensible through plugins. The plugin system lets you add custom remark and rehype plugins, transform graph data, inject elements into the document head, or add components before and after page content. If Grafos does not do something you need out of the box, you can add it without forking the framework.

Fast builds with no surprises. Grafos does not generate OG images at build time, does not run a separate bundler, and does not require a build step beyond what Next.js already provides. The pre-build step is a single pass over your content directory that produces static JSON artifacts. Incremental rebuilds in development watch for file changes and update only what changed.

Designed for real content. Grafos is not a demo or a proof of concept. It is built for sites with dozens to thousands of interconnected pages. The graph rendering uses instanced meshes and Web Worker physics to stay smooth at scale. The search index uses efficient serialization to keep bundle sizes manageable. The sidebar explorer handles deep folder hierarchies with collapsible groups.

Key Features

Grafos ships with a comprehensive set of features designed to work together out of the box:

• 3D Interactive Graph — force-directed graph visualization with local and global views, instanced rendering, and Web Worker physics. See graph for details.
• Full-text Search — client-side search powered by MiniSearch with a Cmd+K keyboard shortcut and fuzzy matching. See search for details.
• Wikilinks — Obsidian-compatible link syntax including page links, aliased links, heading links, and block embeds. See wikilinks for details.
• Backlinks — automatic bidirectional link tracking that shows which pages link to the current page. See backlinks for details.
• Syntax Highlighting — code blocks highlighted by Shiki with support for dozens of languages and themes.
• LaTeX Math — inline and block math expressions rendered by KaTeX through remark-math and rehype-katex.
• Callouts — Obsidian-style callout blocks for tips, warnings, notes, and other admonitions.
• Table of Contents — automatically generated from page headings with scroll-tracking and smooth navigation.
• Dark Mode — dark by default with a toggle that persists in localStorage and renders flash-free via an inline head script.
• On-demand OG Images — social sharing images generated at request time through a Next.js API route, not at build time.
• Plugin System — extend the markdown pipeline, graph data, and page layout with reusable plugins. See plugins for details.
• Tailwind CSS v4 Preset — theming through CSS custom properties with a custom Tailwind preset for consistent styling. See theme for details.

Philosophy

Grafos is built on a few guiding principles that shape every design decision:

Simplicity over sophistication. The best tool is the one you actually use. Grafos keeps its API surface small and its mental model simple. Markdown files go in, a website comes out. Configuration is a single file with sensible defaults. The learning curve should be measured in minutes, not days.

Standards over proprietary systems. Grafos uses Next.js, Tailwind CSS, unified, Three.js, and other well-established tools. When you learn how Grafos works, you are learning transferable skills. When something breaks, you can debug it with standard tools and find answers in standard documentation.

Progressive enhancement. The core experience is a static site built from markdown files. Every advanced feature, from the 3D graph to the search index to server-side rendering optimizations, layers on top of that foundation. You can start simple and add complexity only when you need it.

Content ownership. Your content is yours. It lives in plain text files in your repository. It is not locked into a proprietary format, a hosted service, or a database that you do not control. You can read it with any text editor, version it with git, and move it to another tool at any time.

The graph is a tool, not a toy. Many knowledge management tools include graph views as a visual gimmick. In Grafos, the graph is a real navigation interface. It is designed to help you and your readers understand the structure of your knowledge base and find connections between ideas. It is fast, interactive, and integrated into the reading experience.

Respect for the reader. Grafos sites are fast, accessible, and distraction-free. Pages load quickly because there is no client-side data fetching for content. Navigation is instant because all routes are statically generated. The UI is clean and focused on reading. Dark mode is default because most developers and researchers prefer it, but light mode is one click away.

Next Steps

Ready to get started? Here is the recommended path:

1. installation — install Grafos into a new or existing Next.js project and configure it for the first time.
2. quick-start — scaffold a complete project with the CLI and add your first content pages.
3. configuration — learn about all the options available in grafos.config.ts and how to customize your site.
4. content-directory — understand how Grafos discovers and processes your markdown files.

Once you have a running site, explore the feature guides to learn about the graph, search, wikilinks, backlinks, and plugins systems.