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';
import type { BundledHighlighterOptions, BundledLanguage, BundledTheme } from 'shiki';

interface NorgPluginOptions {
  mode: 'html' | 'react' | 'svelte';
  include?: FilterPattern;
  exclude?: FilterPattern;
  shikiOptions?: BundledHighlighterOptions<BundledLanguage, BundledTheme>;
}

Syntax Highlighting

The plugin automatically applies syntax highlighting to code blocks using Shiki. You can customize the highlighting themes and languages:

norgPlugin({
  mode: 'html',
  shikiOptions: {
    themes: {
      // Optional, GitHub theme applied if none specified
      light: 'github-light',
      dark: 'github-dark',
    },
    // Optional, all langs enabled by default
    langs: ['javascript', 'typescript', 'python'],
  },
});

Review the Shiki documentation for theme and configuration 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

npm install

Development Commands

# Run tests
npm test
cargo test

# Lint and format
nix fmt

License

MIT © Drake Bott