Getting Started

refrakt.md is a content framework built on Markdoc. It extends Markdown with semantic runes — tags that transform standard Markdown primitives into structured, typed content.

Installation

Install the core packages in your project:

npm install @refrakt-md/runes @refrakt-md/content @markdoc/markdoc

Project Structure

A refrakt.md project is a directory of Markdown files:

content/
├── _layout.md
├── index.md
└── docs/
    ├── getting-started.md
    └── runes/
        ├── hint.md
        └── ...

The _layout.md file defines layout regions that wrap every page in that directory and its subdirectories. Pages are regular Markdown files with optional frontmatter.

Your First Layout

Create a _layout.md at the root of your content directory:

{% layout %}
{% region name="header" %}
# My Site
{% /region %}

{% region name="nav" %}
{% nav %}
## Docs
- getting-started
{% /nav %}
{% /region %}
{% /layout %}

This defines a header with your site title and a navigation sidebar. The {% nav %} rune turns the list into page links — display text is pulled from each page's title frontmatter.

Your First Page

Create an index.md:

---
title: Welcome
---

# Hello, refrakt.md

{% hint type="note" %}
This callout was created with the hint rune.
{% /hint %}

Using Runes

Runes are Markdoc tags wrapped in {% %} delimiters. They create interpretation contexts for the Markdown inside them — the same primitives take different meaning depending on the wrapping rune.

Browse the individual rune pages in the sidebar for detailed usage and examples.