vite-plugin-norg

Neorg processor for Vite - Transform .norg files into HTML, React, or Svelte with full TypeScript support.

Built for Neorg users, powered by rust-norg

Installation

npm install -D vite-plugin-norg

Setup

import { defineConfig } from 'vite';
import { norgPlugin } from 'vite-plugin-norg';

export default defineConfig({
  plugins: [
    norgPlugin({
      mode: 'html',
    }),
  ],
});

TypeScript

Add a type reference to app.d.ts based on your output target:

// For Svelte
/// <reference types="vite-plugin-norg/svelte" />

// For React
/// <reference types="vite-plugin-norg/react" />

// For HTML
/// <reference types="vite-plugin-norg/html" />

This provides type checking for .norg modules

HTML Output

import { metadata, html } from './document.norg';
console.log(metadata.title); // "My Document"
document.body.innerHTML = html;

React Output

import { metadata, Component } from './document.norg';

export default function App() {
  return (
    <div>
      <h1>{metadata.title}</h1>
      <Component />
    </div>
  );
}

Svelte Output

<script>
  import Document, { metadata } from './document.norg';
</script>

<h1>{metadata.title}</h1>
<Document />

Configuration Reference

import type { FilterPattern } from 'vite';

interface NorgPluginOptions {
  mode: 'html' | 'react' | 'svelte';
  include?: FilterPattern;
  exclude?: FilterPattern;
  arboriumConfig?: {
    // Single theme
    theme?: string;
    // Or light/dark (uses prefers-color-scheme)
    themes?: {
      light: string;
      dark: string;
    };
  };
}

Code Syntax Highlighting

Code blocks are highlighted using arborium, which generates highlights via tree-sitter. Set a theme to include highlights:

norgPlugin({
  mode: 'html',
  arboriumConfig: { theme: 'github-dark' },
});

See the arborium themes for available options.

Requirements:

• Vite 7.0+
• React 19+ (if using mode: 'react')
• Svelte 5+ (if using mode: 'svelte')

Development

This project uses Nix flakes and direnv for reproducible development environments.

Setup

# Enable direnv
direnv allow

bun install

Development Commands

# Run tests
npm test
cargo test

# Lint and format
nix fmt

License

MIT © Drake Bott