OysterMD

OysterMD is an open-source alternative to Obsidian.md, a local-first knowledge management system based on plain markdown files with bidirectional linking to build an interconnected knowledge graph. OysterMD aims to fully implement Obsidian's features while extending them with new capabilities.

Features:

• AST generation for CommonMark specification, Github-flavored Markdown, and Obsidian-specific extensions¹.
• Static site generator: publish vault to HTML (alternative to Obsidian Publish)
• Optional extensions: Mermaid diagrams, TikZ, Quiver, HTML embeds
• mkq - A standalone jq-inspired CLI for querying Markdown
• More to come: markdown transclusion, UI, LSP...

Installation

From crates.io

cargo install oyster-md

To install with the serve command (local dev server with live reload):

cargo install oyster-md --features serve

From source

git clone https://github.com/hon-gyu/oyster.git
cd oyster
cargo build --release

The binary will be available at ./target/release/oyster.

To build with the serve feature:

cargo build --release --features serve

Usage

Generate Static Site

Generate a static website from your Obsidian vault:

oyster build --output <OUTPUT_DIR> <VAULT_ROOT_DIR>

Available options:

• -o, --output <OUTPUT> - Output directory for the generated site
• -t, --theme <THEME> - Theme to use (available themes: dracula, tokyonight, and gruvbox; default: tokyonight)
• -f, --filter-publish - Whether to only export notes with the publish flag set in the frontmatter
• -p, --preserve-softbreak - Render softbreaks as line breaks
• -m, --mermaid-render-mode <MODE> - Options for rendering mermaid diagrams:
  • build-time: Use mmdc to render at build time
  • client-side: Use mermaid.js in the browser
• --tikz-render-mode <MODE> - Options for rendering TikZ diagrams:
  • build-time: Use latex2pdf and pdf2svg
  • client-side: Use TikZTeX in browser
• --quiver-render-mode <MODE> - Options for rendering Quiver diagrams:
  • build-time: Use latex2pdf and pdf2svg
  • raw-latex: Keep raw LaTeX
• --custom-callout-css <FILE> - Path to custom CSS file for callout customization

Test your generated site locally with:

python3 -m http.server 8000 --directory ./output/site

Then open http://localhost:8000/home.html in your browser.

Progress (⬜ | 🚧 | ✅)

• ✅ Parse markdown using pulldown-cmark and build a syntax tree
• ✅ File / Note reference
• ✅ Heading reference
• ✅ TOC generation
• ✅ Block reference
• SSG
  • ✅ v0: minijina + pulldown-cmarks's html writer; backlinks component; correct links
  • ✅ v1: type-safe ast-based html writer (maud); backlinks component;
  • ✅ more components
    • ✅ TOC
    • ✅ Explorer
    • ✅ Homepage
    • ✅ Sidebar explorer
  • and more components
    • ⬜ Graphview
  • ✅ filter by frontmatter
  • ⬜ Tag page
• Embed image
  • ✅ basic embed
  • ✅ resize embed
• ✅ Embed files:
  • ✅ note, heading, and block
  • pdf, video, audio
  • ✅ HTML
  • ✅ HTML transclusion
  • 🚧 Markdown transclusion
• LaTeX support
  • ✅ basic support (KaTeX)
  • ✅ TikZ; Quiver (extension)
• ✅ Mermaid diagram
• ⬜ Bases
• ✅ Callout
• ✅ Custom callout
• ⬜ CodeGen
• ✅Markdown to structured data (YAML / JSON)
  • ⬜ CHANGELOG validation
  • ✅ query CLI
• ✅ SSG hot reload
• ⬜ LSP (inspired by markdown-oxide)

Long-term

• UI (neovim? Zed fork?)
• Bi-directional sync with
  • Github issues / PRs
  • Github Wiki
  • Linear

Footnotes

1. wikilinks, embeded notes, callouts ↩