https://github.com/bottd/vite-plugin-norg
A Vite plugin to enable processing of .norg files with support for Svelte, React, and HTML
https://github.com/bottd/vite-plugin-norg
Last synced: 2 months ago
JSON representation
A Vite plugin to enable processing of .norg files with support for Svelte, React, and HTML
- Host: GitHub
- URL: https://github.com/bottd/vite-plugin-norg
- Owner: bottd
- License: mit
- Created: 2025-06-22T21:11:12.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-18T05:38:01.000Z (2 months ago)
- Last Synced: 2026-04-18T07:28:00.634Z (2 months ago)
- Language: Rust
- Size: 1 MB
- Stars: 11
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-neorg - vite-plugin-norg - Vite plugin for rendering `.norg` files in the browser (Integrations)
README
# vite-plugin-norg
[](https://www.npmjs.com/package/vite-plugin-norg)
[](https://github.com/bottd/vite-plugin-norg/actions)
[](LICENSE)
**Neorg processor for Vite** - Transform `.norg` files into HTML, React, Svelte, or Vue with full TypeScript support.
## Installation
```bash
npm install -D vite-plugin-norg
```
## Setup
### Configuration
```typescript
import type { FilterPattern } from 'vite';
interface NorgPluginOptions {
mode: 'html' | 'react' | 'svelte' | 'vue' | 'metadata';
include?: FilterPattern;
exclude?: FilterPattern;
arboriumConfig?: {
// Single theme
theme?: string;
// Or light/dark (uses prefers-color-scheme)
themes?: {
light: string;
dark: string;
};
};
// Directory to scan for framework components
componentDir?: string;
// (takes precedence over componentDir)
// { Component: "import-path" }
components?: Record;
}
// vite.config.ts
import { defineConfig } from 'vite';
import { norgPlugin } from 'vite-plugin-norg';
export default defineConfig({
plugins: [
norgPlugin({
mode: 'svelte',
}),
],
});
```
### TypeScript
Add a type reference to `app.d.ts` based on your output target:
```typescript
// For Svelte
///
// For React
///
// For Vue
///
// For HTML
///
// For Metadata
///
```
This provides type checking for `.norg` modules
### HTML Usage
```javascript
import { metadata, html } from './document.norg';
console.log(metadata.title); // "My Document"
document.body.innerHTML = html;
```
### React Usage
```jsx
import { metadata, Component } from './document.norg';
export default function App() {
return (
{metadata.title}
);
}
```
### Svelte Usage
```svelte
import Document, { metadata } from './document.norg';
{metadata.title}
```
### Vue Usage
```vue
import Document, { metadata } from './document.norg';
{{ metadata.title }}
```
### Metadata Usage
```javascript
import { metadata, toc } from './document.norg';
console.log(metadata.title); // "My Document"
console.log(toc); // [{ title: "Section 1", level: 1 }, ...]
```
You can also append `?metadata` to any import to get metadata-only output regardless of mode:
```javascript
import { metadata, toc } from './document.norg?metadata';
```
## Code Syntax Highlighting
Code blocks are highlighted using [arborium](https://arborium.bearcove.eu/), which generates highlights via tree-sitter. Set a theme to include highlights:
```typescript
norgPlugin({
mode: 'html',
arboriumConfig: { theme: 'github-dark' },
});
```
See the [arborium themes](https://github.com/bearcove/arborium?tab=readme-ov-file#themes) for available options.
## Embed Components
Embed components can be referenced within `.norg` documents using `@embed`:
```norg
* Example document
With some regular text
@embed svelte
@end
```
To configure components for usage with embeds, set either `componentDir` or map imports directly with `components`.
```typescript
norgPlugin({
mode: 'svelte',
componentDir: './src/components',
components: {
Chart: './src/lib/Chart.svelte',
},
});
```
## Embed Styles
Document styles can be embedded as well using `@embed css`. All frameworks will import embedded styles when rendering the document.
```norg
* Example document
With some regular text
@embed css
h2 {
color: red;
}
@end
```
**Requirements:**
- Vite 7.0+
- React 19+ (if using `mode: 'react'`)
- Svelte 5+ (if using `mode: 'svelte'`)
- Vue 3+ (if using `mode: 'vue'`)
## Development
This project uses Nix flakes and direnv for reproducible development environments.
### Setup
```bash
# Enable direnv
direnv allow
bun install
```
### Development Commands
```bash
# Run tests
npm test
cargo test
# Lint and format
nix fmt
```
## License
MIT © [Drake Bott](https://github.com/bottd)