Rust library to support the dialect of wiki markup language defined by Zim, a desktop wiki editor
README.md

zimwiki #

Changelog

Rust library to support the dialect of wiki markup language defined by Zim, a desktop wiki editor. See https://zim-wiki.org/

Introduction #

This library parses and serializes Zim's wiki format, which uses a lightweight markup syntax inspired by reStructuredText and Creole.

Scope — v0.1: This is a port of the core parsing logic. The full feature set of the Python reference is not yet implemented.

Implemented:

  • Headings, paragraphs, emphasis, strong, verbatim
  • Bulleted and checkbox lists (numbered lists planned)
  • Internal wiki links [[Page]] and [[Page|Display]]
  • External URLs (auto-detected and manually linked)
  • Tags @word for inline metadata
  • Header line parsing (Content-Type, Wiki-Format, etc.)
  • URL encoding and escaping utilities

Not yet implemented:

  • Tables
  • Images and object embedding
  • Interwiki links
  • Numbered / lettered lists and nested list indentation
  • Indented block (<div>) handling
  • Verbatim blocks with per-line indentation tracking
  • Auto-detected external URLs in inline text
  • Anchors ({{id: ...}})
  • Highlight (__...__), subscript (_{...}), superscript (^{...}), strikethrough (~~...~~)
  • Full round-trip dumping for headings, lists, inline formatting, images, objects, tables, and anchors
  • Unicode whitespace / paragraph-separator normalization and backward-compatibility modes
  • Custom/pluggable tree builder trait (intentionally removed for v0.1)

The implementation mirrors the Python reference in zim/formats/wiki.py from the zim-desktop-wiki project.

Usage #

use zimwiki::parse;

// Parse wiki markup into a parse tree
let input = "==== Heading ====\n\nSome **bold** text.";
let tree = parse(input);

Development #

Setup #

cargo build
cargo test
cargo clippy

Run examples #

Each example is a standalone binary in examples/. Run any of them with cargo run --example <name>:

cargo run --example 01_basic_parse
cargo run --example 02_link_utils
cargo run --example 03_encoding
cargo run --example 04_roundtrip
cargo run --example 06_header_parse

Architecture #

src/
├── lib.rs             # Public API re-exports
├── format.rs          # Element constants
├── format/
│   └── tree.rs        # ParseTree, Node, Element types
└── parse/
    ├── builder.rs        # ParseTreeBuilder implementation
    ├── encode.rs         # URL/escape encoding
    ├── links.rs          # Link detection and classification
    ├── regex_parser.rs   # RegexParser, Rule, parse_header_lines
    ├── wiki_dumper.rs    # WikiDumper — serialize tree to markup
    └── wiki_parser.rs    # WikiParser — state-machine parser, parse()

Key Types #

Type Purpose
parse(input) -> ParseTree Top-level function — parse wiki text to tree
ParseTree Root container holding document nodes and metadata
Node Enum: Start(Element), Text(String), End(&str)
Element Tag name + attributes map
WikiDumper Serialize parse tree back to wiki markup
ParseTreeBuilder Internal builder — exposed for advanced use