orgbuilder: Simple, Professional Document Publishing

• What is orgbuilder?
• Why Use This?
• How It Works (The "Black Box" Analogy)
• Key Features
• Getting Started
  • 1. Prerequisites
  • 2. Folder Structure
  • 3. Running the Builder
• Technical Details (For the Curious)
• Developer Guide: Inner Workings
  • 1. Architecture Overview
  • 2. The Publishing Engine (Emacs Lisp)
  • 3. High-Performance Lisp Integration
  • 4. Persistence & Paths
  • 5. Extending the Builder
  • 6. Customizing LaTeX
  • 7. REQ DSL: Requirements & User Stories
  • 8. Special Blocks: Warning & Info
• For Common Lisp Developers: Documenting Your Projects
  • The Challenge of Documenting Lisp
  • How orgbuilder Solves This:
  • Customizing the Lisp Environment:
• For Technical Writers: Automated Readability & Glossary Management
  • Glossary Management
  • Automated Readability
  • Why This Matters:
• For UX Researchers & Designers: Professionalizing Your Deliverables
  • High-Fidelity Research Reports
  • "Diagrams-as-Code" for User Flows
  • Optimized Design Specs
  • Focus on Content
• Screenshots
  • HTML Output
  • PDF Output

What is orgbuilder?

orgbuilder is a powerful, "all-in-one" digital toolbox designed to turn your plain text notes (written in Org-mode) into beautiful, professional-looking documents like PDFs, websites, and more.

Think of it as a portable publishing house that contains everything you need to create high-quality documents without having to install hundreds of complicated programs on your own computer.

Why Use This?

If you've ever tried to create a professional PDF with complex diagrams or mathematical formulas, you might have discovered that the software required (like LaTeX or Emacs) can be very difficult to set up and keep working correctly.

orgbuilder solves this by:

• Pre-installing everything: It comes with a complete set of professional typesetting tools (LaTeX), diagram creators (PlantUML, Graphviz), and document converters (Pandoc).
• Consistency: It works exactly the same way on every computer (Windows, Mac, or Linux).
• Simplicity: You write your content in simple text files, and the "builder" handles the complex conversion process for you.

How It Works (The "Black Box" Analogy)

You don't need to be a programmer to use this. Imagine orgbuilder as a black box:

1. You put your Source Documents (simple .org text files) into a folder.
2. You run a single command to start the box.
3. The box processes your files and gives you a Public Folder containing your finished PDFs or HTML files.

Key Features

• Beautiful PDFs: Uses professional-grade typesetting (LuaLaTeX) for books, reports, and articles.
• Websites & Blogs: Quickly turn your notes into clean, readable HTML.
• Diagrams & Charts: Automatically generates diagrams from simple text descriptions (using PlantUML and Graphviz).
• Automatic WebP Conversion: Automatically converts JPEG and PNG images to the modern WebP format for HTML exports, ensuring fast page loads.
• Requirements & User Stories: A built-in DSL (REQ) for defining and validating dependencies between requirements or user stories, including automatic graph generation and cycle detection.
• Modern Markdown: Creates GitHub-compatible Markdown files if you need to share your work on developer platforms.
• Special Blocks (Warning & Info): Easily highlight important information or warnings using custom Org-mode blocks that look great in both PDF and HTML.

Getting Started

1. Prerequisites

You only need one piece of software installed on your computer:

• Docker Desktop (or Podman)

2. Folder Structure

Organize your project like this:

my-project/
├── src/            <-- Put your .org files here
│   └── data/       <-- Put static assets here (logo.png, etc.)
│       └── static/ <-- Configuration and assets
│           ├── orgbuilder.css (automatically copied)
│           ├── preamble.html  (automatically copied)
│           └── postamble.html (automatically copied)
├── public/         <-- Your finished documents will appear here
├── plantuml/       <-- Optional: Put your custom plantuml.puml here
└── texmf/          <-- Put your custom LaTeX styles (.sty) here (e.g., orgbuilder.sty)

orgbuilder comes with professional defaults for all output formats. These templates and styles were crafted by a professional UX designer, ensuring high standards for accessibility, typography, and aesthetics. The visual identity is built upon the popular Nord theme color palette, providing a clean, focused, and modern reading experience across all devices.

• Custom Styles: To customize the look of your PDFs, you can place your own version of orgbuilder.sty inside the texmf/ folder.
• Custom CSS: The builder automatically copies a default orgbuilder.css to src/data/static/orgbuilder.css if it doesn't already exist.
• HTML Preamble & Postamble: The builder automatically copies default preamble.html and postamble.html files to src/data/static/ if they don't already exist. You can then modify these files to customize your project's header and footer.
• Relative Paths: The builder automatically handles relative paths for CSS, images, and links in your headers, preambles, and postambles, ensuring everything works perfectly even with deep folder structures.
• PlantUML Config: You can provide a custom plantuml/plantuml.puml to configure diagram styles.

3. Running the Builder

Once you have your files ready, you run the container and it will automatically find your files in src/ and publish them to public/. The process provides detailed logs prefixed with ORGBUILDER: for easy troubleshooting.

Technical Details (For the Curious)

Under the hood, orgbuilder uses:

• Fedora Linux: A stable and modern foundation.
• Emacs: The engine that understands Org-mode.
• TeX Live: The industry standard for high-quality typesetting.
• SBCL (Common Lisp): A fast programming language used for advanced document processing features.
• Pandoc: The "swiss-army knife" of document conversion.

Developer Guide: Inner Workings

This section is for developers who want to understand how the container is built or how to extend its publishing capabilities.

1. Architecture Overview

The container is built on Fedora Minimal to keep the size down while providing a robust environment for LaTeX and Emacs.

• Orchestration: We use just (see justfile) for common tasks like building and pushing the image.
• Entry Point: The orgbuilder.sh script handles pre-flight checks (verifying required directories) and then invokes Emacs in batch mode.

2. The Publishing Engine (Emacs Lisp)

The heart of the system is orgbuilder.el. It defines:

• Project Alist: Configures how different file types are handled.
• Custom Backends: Uses ox-pandoc to provide pandoc-html5 and pandoc-md export options.
• Automatic WebP Conversion: For HTML-based exports, the builder automatically converts JPEG and PNG files to WebP using ImageMagick. It also includes an export filter that rewrites image links in the generated HTML to ensure they point to the optimized .webp assets.
• Environment Control: The PUBLISH environment variable can be set to trigger specific functions (e.g., PDF, HTML, MD).

3. High-Performance Lisp Integration

A unique feature of orgbuilder is its deep integration with Common Lisp (SBCL) for code execution within Org files.

• Pre-built Core: To avoid the slow startup of loading Quicklisp libraries at runtime, we pre-install libraries and "dump" a custom SBCL memory image to /opt/sbcl/sbcl.core.
• Instant Execution: The org-babel-execute:lisp function in orgbuilder.el is customized to use this core image, making Lisp code block execution nearly instantaneous.
• Library Management: To add new Lisp libraries, modify lisp-package-install.lisp and rebuild the container.

4. Persistence & Paths

To ensure the container remains "immutable" while allowing for user content:

• Emacs packages are installed to /opt/emacs-packages/.
• Quicklisp is installed to /opt/quicklisp/.
• Your project is typically mounted to /home/book/.

5. Extending the Builder

If you need to add custom Emacs Lisp configuration without rebuilding the image, you can mount a file to ~/extend-orgbuilder.el inside the container. The main orgbuilder.el will automatically load it if it exists.

6. Customizing LaTeX

The default LaTeX class is orgbuilder, which includes the orgbuilder package.

• Default Style: A basic orgbuilder.sty is included in the image at /opt/texmf/tex/latex/orgbuilder/orgbuilder.sty.
• Overriding: To override the default style, simply provide your own orgbuilder.sty file in your project's texmf/ directory.
• Custom Classes: You can also use other LaTeX classes (like koma-general) by specifying them in your Org-mode file's header (e.g., #+LATEX_CLASS: koma-general).

7. REQ DSL: Requirements & User Stories

For software engineering and project management, orgbuilder includes a built-in Domain-Specific Language (REQ) for managing dependencies between requirements or user stories.

• Usage: Define requirements using standard Org-mode headlines with :ID: and :DEPENDS_ON: properties.

  * TODO User Authentication
    :PROPERTIES:
    :ID: REQ-AUTH-01
    :END:
  
  * TODO Profile Management
    :PROPERTIES:
    :ID: REQ-PROF-01
    :DEPENDS_ON: REQ-AUTH-01
    :END:

• Automatic Graphing: Insert #+name: req-graph in your document. The builder will automatically generate a dependency graph (PNG) in src/data/ and insert a link to it at the placeholder.

• Validation (The "Build Stopper"): During export, the builder automatically validates your requirements for:

  • Duplicate IDs: Ensures every requirement is unique.
  • Dangling References: Ensures all dependencies point to existing IDs.
  • Cycle Detection: Detects and reports circular dependencies (e.g., A -> B -> A).

  If validation fails, the build process will terminate with a non-zero exit code, preventing inconsistent documentation from being published.

8. Special Blocks: Warning & Info

orgbuilder provides custom semantic blocks for highlighting important information or warnings. These are implemented using standard Org-mode Special Blocks:

• Usage:

  #+BEGIN_warning
  This is a critical warning that needs attention.
  #+END_warning
  
  #+BEGIN_info
  This is a helpful tip or informative note.
  #+END_info

• HTML Implementation:

  • Exported to <div class"warning">= or <div class"info">=.
  • Styled in orgbuilder.css with Bootstrap Icons automatically added as prefixes.
  • Fully supports Dark Mode with high-contrast color overrides.

• LaTeX Implementation:

  • Exported to \begin{warning} or \begin{info} environments.
  • Defined in orgbuilder.sty using the tcolorbox package.
  • Features FontAwesome5 icons, colored sidebars, and uses the Noto Sans font for clear readability.

For Common Lisp Developers: Documenting Your Projects

If you are building and documenting Common Lisp systems, orgbuilder provides a highly optimized, frictionless environment for generating system documentation, tutorials, and literate programming artifacts.

The Challenge of Documenting Lisp

Writing good documentation for Common Lisp often involves executing code blocks to generate examples, tests, or API references directly within the document. Traditional setups require a complex interplay of Emacs, SLIME/SLY, SBCL, Quicklisp, and specific Org-babel configurations. This makes reproducing the documentation build environment across different machines or in CI pipelines notoriously difficult and slow.

How orgbuilder Solves This:

• Instant, Silent Code Execution: Standard Org-Babel usually starts a fresh Lisp process and loads Quicklisp for every code block. orgbuilder uses a custom SBCL core image where Quicklisp and essential libraries are pre-loaded in memory. Execution is instantaneous, and initialization noise is completely suppressed.
• "Resident" Libraries for Examples: Popular utility libraries (like alexandria, drakma, dexador, shasht, and spinneret) are pre-baked into the image. You can write code examples using these libraries immediately without polluting your document with (ql:quickload ...) calls.
• True Reproducibility: Because orgbuilder is containerized, every contributor and CI runner uses the exact same SBCL version, core image, and library versions. If the documentation builds on your machine, it will build identically everywhere else.
• Zero-Config Literate Programming: You get a fully configured environment for Literate Programming out of the box. Write your documentation and code together in Org-mode, and rely on orgbuilder to execute the code and format the output beautifully into PDF or HTML.

Customizing the Lisp Environment:

• Baking in Your System: If you want your own Common Lisp system to be instantly available in code blocks for API documentation, you can add it to lisp-package-install.lisp and rebuild the orgbuilder container. It will be permanently dumped into the core image.
• Dynamic Loading: For ad-hoc library requirements, you can still use (ql:quickload ...) within your code blocks. Downloaded libraries are cached in a persistent volume at /opt/quicklisp/ for subsequent builds.

For Technical Writers: Automated Readability & Glossary Management

To ensure your documentation is accessible and perfectly aligned with your audience, orgbuilder includes automated tools.

Glossary Management

orgbuilder features an automated, cross-format glossary system. It parses a single source of truth and generates native, semantic glossary implementations for HTML, PDF, and Texinfo.

1. Define your terms: Create a glossary.org file in your src/ directory. Define each term as an Org-mode heading with specific properties:

   * My Term
   :PROPERTIES:
   :ID: my-term
   :DESCRIPTION: A clear explanation of what this term means.
   :SHORT: MT
   :END:

   • ID: (Required) The unique identifier used to link to this term.
   • DESCRIPTION: (Required) The full definition.
   • SHORT: (Optional) An abbreviation.

2. Link to terms: In your document, use the custom term: link type:

   The [[term:my-term]] is used throughout this document.
   

3. Include the Glossary: Add an include directive where you want the glossary to appear:

   #+include: glossary.org
   

How it works across formats:

• HTML: Generates semantic <abbr> tags with tooltips for inline links, and a definition list (<dl>) for the glossary page.
• PDF (LaTeX): Automatically injects \newglossaryentry and \newabbreviation definitions into the preamble and uses the glossaries package (\gls) for correct expansion and indexing.
• Texinfo/Info: Creates native @ref links and a dedicated index node for easy navigation within Emacs or the command line.

Automated Readability

Every time you publish a document (PDF or HTML), the builder automatically evaluates your text using the Flesch-Kincaid Grade Level analyzer and provides a report in the build logs:

ORGBUILDER: [Readability] README.org -> Grade Level: 9.4 | Words: 842 | Sentences: 52

Why This Matters:

• Audience Alignment: If you're writing for a general audience, aim for Grade 8–10. For expert manuals, Grade 12–14 might be appropriate.
• Accessibility: Lower grade levels generally lead to better comprehension for non-native English speakers.
• Objective Feedback: Instead of guessing if your sentences are too complex, you get immediate data points.
• Smart Parsing: The analyzer is "Org-aware"—it automatically ignores code blocks, metadata, and drawers, ensuring the score reflects your actual prose, not your technical implementation.

For UX Researchers & Designers: Professionalizing Your Deliverables

For UX professionals, orgbuilder provides a bridge between rigorous research and high-fidelity presentation, allowing you to maintain a "Single Source of Truth" for your design documentation.

High-Fidelity Research Reports

UX Researchers need to deliver findings to stakeholders in a format that feels authoritative.

• Academic-Quality Typesetting: By using LaTeX (LuaLaTeX), orgbuilder produces PDFs with superior typography, kerning, and layout compared to standard word processors.
• Visual Consistency: Use a global orgbuilder.sty (LaTeX) or orgbuilder.css (HTML) to ensure every research paper, persona, or usability report follows your brand guidelines automatically.

"Diagrams-as-Code" for User Flows

Instead of jumping into design tools for every minor change to a site map or user journey:

• Speed: Describe user flows in text (e.g., using PlantUML). The builder automatically renders them into clean SVGs or PNGs.
• Version Control: Because diagrams are text-based, you can track exactly how a user flow evolved over time in Git—something nearly impossible with binary design files.

Optimized Design Specs

Maintain a single .org file that contains the "Why" (research data), the "How" (specifications), and the "What" (embedded diagrams).

• Automated Image Optimization: The builder automatically converts your high-resolution screenshots to WebP, ensuring that developers or stakeholders viewing your HTML reports experience fast load times.
• Reproducible Data Analysis: Include Python or Lisp code blocks to process survey results or task success rates. The charts and tables update automatically if the underlying data changes, preventing manual copy-paste errors.

Focus on Content

Org-mode's "folding" and structured writing environment allow you to manage massive research projects without getting lost in the formatting. Focus entirely on the analysis and insights, while orgbuilder handles the "janitorial" work of generating tables of contents, cross-references, and bibliographies.

Screenshots

HTML Output

PDF Output