Skip to content

Instantly share code, notes, and snippets.

@mcoderz

mcoderz/gutenberg.md

Last active February 4, 2026 23:13
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save mcoderz/7adcd2a940318ebc17420c27d742e3fa to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save mcoderz/7adcd2a940318ebc17420c27d742e3fa to your computer and use it in GitHub Desktop.
Download ZIP
Project Codename: Gutenberg
Raw
gutenberg.md

Project Codename: Gutenberg

A Semantic Workbench for AsciiDoc

Target Architecture: Tauri (Rust) + Webview
Status: Request for Comment (RFC)

1. The Philosophical Premise

We do not need another markdown note-taking app. We do not need a word processor that hides complexity behind a "What You See Is What You Get" (WYSIWYG) curtain.

The AsciiDoc Manifesto teaches us that content is data, and markup is structure. The current tooling landscape forces engineers to choose between:

  1. Generic IDEs (VS Code): Powerful, but agnostic to the specific semantic weight of AsciiDoc.
  2. Simple Editors: Good for prose, but incapable of handling complex, modular documentation systems.

Gutenberg is proposed as an Integrated Writing Environment (IWE). It treats AsciiDoc not as flat text, but as a directed graph of included files, attributes, and semantic nodes. It prioritizes the writer's flow (UI/UX) while enforcing the rigors of version control and modularity (Engineering).

2. Core Architectural Principles

2.1 The "Source-First" Doctrine

In compliance with the "Docs-as-Code" philosophy, the source text is the single source of truth.

  • No Hiding Markup: We will not use rich-text replacement (e.g., turning *bold* into just bold text without the asterisks). The user must see the syntax to understand the structure.
  • Visual Assistance, Not Abstraction: Instead of hiding syntax, we dim it (syntax highlighting) or augment it (badges for attributes), but the raw bytes remain editable.

2.2 The "Forest, Not Trees" View (Modularity)

AsciiDoc shines in its ability to compose documents via include::.

  • The Problem: Most editors treat files in isolation.
  • The Solution: Gutenberg must parse the entire document tree. If book.adoc includes chapter1.adoc, the editor must understand the variable scope (attributes) inherited by the child file.

3. Technical Specification (Tauri & Rust)

3.1 The Backend: Rust (The Heavy Lifter)

The Rust backend is not merely a file server; it is a Language Server and a State Manager.

  • The Semantic Graph (AST):

    • Decision: We will not rely solely on the Ruby asciidoctor CLI for analysis, as it is too slow for real-time typing feedback.
    • Implementation: We will implement a lightweight Recursive Descent Parser in Rust that generates a concrete syntax tree (CST).
    • Purpose: This allows instant "Go to Definition" for includes, attribute validation, and outline navigation without waiting for a full HTML render.

  • Git Integration (git2-rs):

    • Git operations happen on the Rust thread to avoid freezing the UI.
    • Feature: Semantic Diffing. Instead of purely line-based diffs, we can show diffs based on blocks (e.g., "You modified this Admonition Block").

3.2 The Frontend: Webview (The Interface)

  • Editor Component: usage of Monaco or CodeMirror 6.

    • Reasoning: We need accessible APIs for custom decorators (widgets inline with text) to render things like math equations (LaTeX) or color previews without altering the source text.

  • Rendering:

    • For the preview pane, we will use asciidoctor.js initially for compatibility, but the architecture must allow swapping this for a Rust-native HTML generator (asciidoc-rs) in the future to achieve sub-millisecond rendering.

4. Feature Requirements

4.1 Intelligent Writing Assistance

The editor must offer "IntelliSense" for prose:

  • Attribute Autocompletion: If {product-version} is defined in component.adoc, it should be suggested in page.adoc.
  • Broken Link Guard: Real-time checking of image paths and cross-references. Rust checks the filesystem; if the image doesn't exist, the line number is flagged immediately.
  • Table Management: ASCII tables are painful to format manually. The editor must auto-format pipe | alignment upon save.

4.2 The "Zen" Interface (UI/UX)

  • Distraction-Free Mode: A toggle to hide the file tree, git status, and preview, leaving only the source text centered.
  • Sync-Scrolling: The Preview pane must mathematically align with the Source pane using AST node mapping, not just percentage-based scrolling (which fails when images are present).

4.3 Git & Version Control

  • Atomic Commits: A dedicated UI for staging specific lines (hunks).
  • Branch Management: Create and switch branches directly from the status bar.
  • Conflict Resolution: A 3-way merge view specifically designed for text documents.

5. The "Rust Processor" Dilemma (ADR)

Context: Should we write the AsciiDoc processor from scratch in Rust?

  • Analysis: Writing a fully compliant AsciiDoc processor is a multi-year effort.
  • Verdict: Hybrid Approach.
    1. Use Rust for the Analysis Layer (Parsing structure, finding references, validating links).
    2. Use Asciidoctor (JS/Ruby) for the Presentation Layer (Final HTML export).

This gives us the performance of Rust for the typing experience, without losing the feature parity of the official converter.

6. Call to Action (Why build this?)

We are engineers. We write design docs, RFCs, and manuals. The tools we use shape the way we think. If we use tools that treat documentation as second-class citizens, our documentation will reflect that.

We are building Gutenberg to restore dignity to technical writing. We are looking for Rustaceans and Frontend Engineers who understand that a great tool is transparent—it disappears, leaving only the flow between the mind and the screen.

Tech Stack:

  • Core: Rust (Tauri v2)
  • UI: React/Svelte + Tailwind
  • State: Redux or Rust-managed State
  • VCS: libgit2
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment