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 Technical Writers: Automated Readability
  • Why This Matters:
• 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 Technical Writers: Automated Readability

To ensure your documentation is accessible and perfectly aligned with your audience, orgbuilder includes an automated Flesch-Kincaid Grade Level analyzer.

Every time you publish a document (PDF or HTML), the builder automatically evaluates your text 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.

Screenshots

HTML Output

PDF Output