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 />

Architecture

graph LR
    A(📝 .norg files) ==> B(⚡ Rust Parser)
    B ==> C(🔧 NAPI Module)
    C ==> D(🚀 Vite Plugin)
    D ==> E{🎨 Generator}
    E ==> F(📄 HTML)
    E ==> G(⚛️ React)
    E ==> H(🔥 Svelte)
    F ==> I(💎 TypeScript Module)
    G ==> I
    H ==> I

    linkStyle default stroke-width:3px

Configuration Reference

import type { FilterPattern } from 'vite';

interface NorgPluginOptions {
  mode: 'html' | 'react' | 'svelte';
  include?: FilterPattern;
  exclude?: FilterPattern;
  // See https://shiki.style/guide for all options
  shikiOptions?: {
    themes?: {
      // optional: defaults to 'github-light'
      light: string;
      // optional: defaults to 'github-dark'
      dark: string;
    };
  };
}

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

npm install

Development Commands

# Run tests
npm test
cargo test

# Lint and format
nix fmt

License

MIT © Drake Bott