7.8 KiB

Raw Blame History

Scriptorium Nostr

An Obsidian plugin for creating, editing, and publishing Nostr document events directly from your vault.

Author: Silberengel
Homepage: https://gitcitadel.com
Lightning tips: gitcitadel@getalby.com

Features

Multiple event kinds: Markdown (1, 11, 30023, 30817) and AsciiDoc (30040, 30041, 30818)
Automatic structure parsing: AsciiDoc documents with headers are parsed into nested 30040/30041 event hierarchies
NKBIP-08 support: Hierarchical book wikilinks with optional collection tags for compendiums, digests, and libraries
Flexible structure: Supports both two-level (book + chapters) and three-level (book + chapters + sections) hierarchies
Metadata in files: Metadata stored directly in Markdown frontmatter or AsciiDoc header attributes
Two-step workflow: Create/sign events separately from publishing to relays
Automatic relay management: Fetch relay lists (kind 10002) with AUTH support

Quick Start

Installation

# First run (vault path required)
./start-obsidian.sh ~/Documents/MyVault

# Subsequent runs (path saved)
./start-obsidian.sh

The script automatically installs dependencies, builds the plugin, and starts Obsidian.

Setup

Generate a Nostr key (if needed):
```
./start-obsidian.sh --generate-key
```
Add the shown export command to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Set your private key:

export SCRIPTORIUM_OBSIDIAN_KEY="nsec1..."

Configure relays:
- Open Obsidian Settings → Scriptorium Nostr
- Click "Fetch" to get your relay list

Usage

Creating Events

Open a Markdown or AsciiDoc file
Run command: Create Nostr Events
A reminder modal will prompt you to update metadata
Update metadata in the file (see Metadata section below)
Click "OK" in the modal
Events are created, signed, and saved to {filename}_events.jsonl

Publishing Events

Ensure events exist ({filename}_events.jsonl)
Run command: Publish Events to Relays
Events publish to all configured write relays

Other Commands

Edit Metadata - Open metadata editor for current file
Preview Document Structure - Show event hierarchy (AsciiDoc structured documents only)
New Nostr Document - Create a new document with metadata template

File Formats

Markdown Files (`.md`)

Supported event kinds: 1, 11, 30023, 30817

Metadata is stored in YAML frontmatter at the top of the file:

---
kind: 30023
title: "My Article"
author: "Author Name"
summary: "Article summary"
image: "https://example.com/image.jpg"
topics: "bitcoin, nostr"
published_at: "1234567890"
---

AsciiDoc Files (`.adoc`)

Supported event kinds: 30040, 30041, 30818

Simple AsciiDoc (kind 30818):

= Wiki Page Title

:kind: 30818
:author: Author Name
:summary: Page description
:image: https://example.com/image.jpg
:topics: bitcoin, nostr

Structured AsciiDoc (kind 30040 with nested 30041):

= Book Title

:kind: 30040
:author: Author Name
:type: book
:summary: Book description
:collection_id: bible
:version_tag: kjv

== Chapter 1

Chapter content here...

=== Section 1.1

Section content...

Two-level structure (book + chapters, no sections):

= Book Title

:kind: 30040
:author: Author Name
:type: book
:summary: Book description

== Chapter 1

Chapter content here...

== Chapter 2

Chapter content here...

In two-level structures, chapters are created as 30041 events directly under the root 30040.

When publishing, metadata is automatically stripped from content before creating events.

NKBIP-08 Tag Inheritance

For structured AsciiDoc documents (kind 30040), NKBIP-08 tags are automatically assigned based on the document hierarchy:

C tag (collection_id): Optional, set in root 30040 metadata. If set, inherited by all events in the hierarchy. Use for compendiums, digests, or libraries of related books (e.g., "bible", "goethe-complete-works", "encyclopedia-britannica").
T tag (title_id): Always set from root 30040 book title, inherited by all nested events.
c tag (chapter_id):
- Two-level structure: from 30041 chapter title (chapters are 30041 events)
- Three-level structure: from parent 30040 chapter title
s tag (section_id): Only in three-level structures, from 30041 section title
v tag (version_tag): If set in root 30040, inherited by all events in the hierarchy

All tag values are normalized per NKBIP-08 spec (lowercase, hyphens, numbers only).

Event Kinds

Kind	Format	Description	Title Required
1	Markdown	Normal note	No
11	Markdown	Discussion thread OP	Yes
30023	Markdown	Long-form article	Yes
30040	AsciiDoc	Publication index	Yes
30041	AsciiDoc	Publication content	Yes
30817	Markdown	Wiki page	Yes
30818	AsciiDoc	Wiki page	Yes

Stand-alone vs Nested 30041

Stand-alone 30041: Uses NKBIP-01 tags (d, title, image, summary, published_at, topics)
Nested 30041 (under 30040): Uses NKBIP-08 tags
- Two-level structure (book + chapters): 30041 events are chapters (c tag from chapter title, no s tag)
- Three-level structure (book + chapters + sections): 30041 events are sections (c tag from parent chapter, s tag from section title)
- All nested 30041 events inherit C tag (collection_id) and v tag (version_tag) from root 30040
- All nested 30041 events get T tag (title_id) from root 30040 book title

Metadata Fields

All predefined metadata fields are shown in frontmatter/attributes with placeholder descriptions. Remove or update placeholders you don't need. Placeholder values are automatically skipped when creating events.

Common Fields

kind - Event kind (required)
title - Document title (required for all except kind 1)
author - Author name
summary - Brief description
topics - Comma-separated topics (available for all event kinds)
image - Image URL (available for 30023, 30040, 30041, 30817, 30818)

Kind-Specific Fields

30023 (Article):

published_at - Unix timestamp

30040 (Publication Index):

type - Publication type (book, illustrated, magazine, documentation, academic, blog)
version - Version or edition
published_on - Publication date
published_by - Publisher
source - Source URL
auto_update - Auto-update behavior (yes, ask, no)
collection_id - NKBIP-08 collection identifier (C tag) - Optional: compendium, digest, or library of related books (e.g., "bible", "goethe-complete-works", "encyclopedia-britannica"). If set in root 30040, inherited by all events in the hierarchy.
version_tag - NKBIP-08 version identifier (v tag) - If set in root 30040, inherited by all events in the hierarchy

30041 (Publication Content):

Stand-alone: Same as 30023 (image, summary, published_at, topics)
Nested (under 30040): NKBIP-08 tags
- collection_id - Inherited from root 30040 (C tag)
- title_id - From root 30040 book title (T tag)
- chapter_id - From chapter title (c tag)
  - Two-level: from 30041's own title (it is the chapter)
  - Three-level: from parent 30040's title
- section_id - From 30041's title (s tag) - Only in three-level structures
- version_tag - Inherited from root 30040 (v tag)

Manual Installation

Clone repository
Run npm install && npm run build
Copy main.js and manifest.json to .obsidian/plugins/scriptorium-obsidian/
Enable in Obsidian Settings → Community Plugins
Install obsidian-asciidoc plugin (required for .adoc files)

Development

npm install
npm run dev    # Watch mode
npm run build  # Production build

License

MIT

7.8 KiB Raw Blame History