nuartz is a monorepo with two main packages:
packages/nuartz: the core library that handles markdown processingapps/web: the Next.js application that renders your digital garden
Processing pipeline
During bun run generate (scripts/prebuild.ts), nuartz processes every published note through a unified pipeline defined in packages/nuartz/src/markdown.ts. The exact plugin order is on the Processing Pipeline page.
- Frontmatter extraction: gray-matter parses YAML frontmatter into structured data
- Remark (Markdown → Markdown AST): The markdown is parsed with remark-parse into an mdast tree, then transformed by remark plugins:
remark-frontmatter: handles YAML/TOML blocksremark-gfm: GitHub Flavored Markdown (tables, strikethrough, etc.)remark-math: LaTeX math syntaxremark-breaks: soft line breaks- Custom nuartz plugins:
remarkObsidianComment,remarkEmbed,remarkBlockIds,remarkWikilink,remarkCallout,remarkTag,remarkHighlight,remarkArrows
- Remark → Rehype: The markdown AST is converted to an HTML AST (hast) via remark-rehype
- Rehype (HTML AST → HTML AST): Rehype plugins transform the HTML tree:
rehype-raw: pass-through raw HTML@beoe/rehype-graphviz,@beoe/rehype-d2: diagrams rendered to inline SVGrehype-pretty-code: syntax highlighting with dual themesrehype-slug+rehype-autolink-headings: heading anchorsrehype-katex: LaTeX renderingrehypeExtractToc: extracts table of contents from headingsrehypeExcerpt: plain-text excerpt of the leading paragraphs
- Stringify: rehype-stringify serializes the HTML AST to an HTML string
The pipeline returns a RenderResult containing the HTML, frontmatter, table of contents, outgoing links, tags, and excerpt.
Key types
Defined in packages/nuartz/src/types.ts:
interface RenderResult {
html: string
frontmatter: Frontmatter
toc: TocEntry[]
links: string[] // outgoing note links
tags: string[] // frontmatter tags followed by inline #tags
inlineTags: string[] // inline #tags in document order
excerpt: string // plain text of the leading paragraphs
}
interface RenderOptions {
baseUrl?: string
resolveLink?: (target: string, heading?: string, filePath?: string) => string
resolveEmbed?: (target: string, filePath?: string) => { content: string; filePath: string } | undefined
resolveAsset?: (target: string, filePath?: string) => string | undefined
resolveTag?: (tag: string) => string
knownSlugs?: Set<string>
stripDrafts?: boolean
filePath?: string
features?: { wikilinks?: boolean; callouts?: boolean; tags?: boolean; toc?: boolean }
}The web application
apps/web is a standard Next.js App Router application:
app/layout.tsx: root layout with sidebar, theme provider, and global stylesapp/[...slug]/page.tsx: catch-all route that reads the page, folder, and alias datageneratewrote to.generated/and displays it. Notes are not rendered at request time.content/: your markdown files live here, organized by foldercomponents/: React components for the graph view, table of contents, navigation, etc.
File utilities
packages/nuartz/src/fs.ts provides helpers for reading and discovering content files, building the file graph for backlinks and the graph view.
Custom plugins
nuartz plugins live in packages/nuartz/src/plugins/ and are standard unified plugins: either remark (operating on mdast) or rehype (operating on hast). See creating-plugins for details on writing your own.