Plugins | Grafos

Extend Grafos with plugins that add markdown transforms, graph modifications, and custom UI.

Grafos has a plugin system that lets you extend the framework without modifying its source code. Plugins can add markdown processing steps, transform graph data, inject elements into the page head, and add components before or after page content.

What Are Plugins?

A Grafos plugin is a JavaScript object that implements one or more hooks. Each hook runs at a specific point in the build or render process and receives data that it can read or modify.

Plugins let you:

Add custom remark or rehype plugins to the markdown pipeline
Transform the graph data after it is generated (add, remove, or modify nodes and edges)
Inject <meta>, <link>, or <script> tags into the document <head>
Render React components before or after the page content

This design keeps the Grafos core small and focused while letting the community build extensions for specialized use cases.

Using Plugins

Plugins are added to the plugins array in configuration:

import { defineConfig } from 'grafos'
import { grafosReadingTime } from 'grafos-reading-time'
import { grafosMermaid } from 'grafos-mermaid'

export default defineConfig({
  plugins: [
    grafosReadingTime(),
    grafosMermaid({ theme: 'dark' }),
  ],
})

Plugins are applied in the order they appear in the array. If two plugins modify the same data, the second plugin receives the output of the first.

Some plugins accept configuration options passed as function arguments. Check each plugin's documentation for available options.

Grafos publishes official plugins under the @grafos/ npm scope. Community plugins typically use the grafos- naming prefix.

Available Plugins

Grafos ships with several built-in plugins that can be enabled through configuration feature flags. The plugin system is also open for third-party and custom plugins.

Built-in capabilities available via config:

Feature	Description
Wikilinks	Obsidian-compatible `[[link]]` syntax. See wikilinks.
Callouts	Obsidian-style `> [!type]` callout blocks.
Math	LaTeX rendering via KaTeX.
Syntax highlighting	Code block highlighting via Shiki.

These are not technically plugins (they are built into the core pipeline), but they follow the same pattern: each adds remark or rehype transforms to the unified pipeline.

Community plugin ideas:

Reading time — calculate and display estimated reading time per page
Mermaid — render Mermaid diagrams in fenced code blocks
Last modified — show git-based last modified dates
Related pages — suggest pages based on shared tags or content similarity
Analytics — inject client-side analytics scripts

See creating-plugins for a guide on building your own plugins.

Plugin Hooks

Plugins interact with Grafos through hooks. Each hook is an optional property on the plugin object:

interface GrafosPlugin {
  name: string

  // Markdown pipeline hooks
  remarkPlugins?: RemarkPlugin[]
  rehypePlugins?: RehypePlugin[]

  // Graph data hook — runs after graph.json is generated
  transformGraph?: (graph: GraphData) => GraphData

  // Head injection hook — returns elements to add to <head>
  head?: () => React.ReactNode

  // Content wrapper hooks — render before/after page content
  beforeContent?: (props: PageProps) => React.ReactNode
  afterContent?: (props: PageProps) => React.ReactNode
}

remarkPlugins and rehypePlugins are arrays of unified plugins that are appended to the markdown pipeline. They run after the built-in transforms.

transformGraph receives the full graph data (nodes and edges) and returns a modified version. Use this to add virtual nodes, remove edges, or compute custom properties.

head returns React elements that are rendered inside the <head> tag. Use this for analytics scripts, custom meta tags, or external stylesheet links.

beforeContent and afterContent receive the current page's props and return React elements rendered immediately before or after the markdown content. Use this for banners, reading time displays, or feedback widgets.

Remark and rehype plugins from all Grafos plugins are concatenated in order and appended after the built-in pipeline. If your plugin depends on another plugin's output, make sure it appears later in the plugins array.