Static Generator

Beyond Websites: Disseminate's Novel Approach to Static Site Generation Free and Open-source

Disseminate - is Not your Typical Website Static Generator, It Generates Books and Novels as a Static Sites

Hazem Abbas

Jun 3, 2024 — 5 min read

Disseminate is a comprehensive document processing system and static site generator. Tailored to handle a wide variety of documents including textbooks, books, novels, articles, reports, and essays, it offers a unique blend of functionality and simplicity.

Its versatility makes it an ideal tool for a range of users, from academics to non-academics.

At the core of Disseminate is a unique markup language, written in Disseminate text format (.dm). This language is designed with a simple and consistent syntax, which allows for a clean and straightforward project structure.

The application's projects can range from a single document to a complex tree of interconnected documents comprising chapters, raw data, figures, and images. These projects are managed in a source-controlled repository, ensuring systematic organization and easy accessibility.

Python and Open-source

Coded in Python 3, Disseminate is completely open-source project that provides the flexibility to convert projects into several different formats. These include .html, .txt, .tex, .pdf, and .epub, catering to a variety of user requirements.

The application's latest version is readily available on GitHub, solidifying Disseminate as a reliable and effective tool for document processing and static website generation.

Key Features

Controlled Versioning: Disseminate allows the storage of document projects in source code repositories, facilitating change tracking, multi-author contributions, and raw data inclusion.
Macros: Disseminate provides macros for users to generate custom tags for frequently used code snippets. These macros are defined in the document header and are available for all sub-documents.
Unified Tag Syntax: All tags in Disseminate adhere to a simple format. Some tags offer enhanced typesetting functionality, and attributes can be added to format the tag rendering. For example, This is @b{my} sentence. or @img[width=40%]{src/figure-1.png}.
Document Headers and Bodies: Documents in Disseminate can optionally include a YAML header to configure the document and a body written in disseminate syntax.
Inline Diagrams and Plots: Tags in Disseminate can process raw data and code, which are then automatically rendered into images, figures, and diagrams.
Automatic File Conversions: Disseminate includes a custom build automation system that efficiently identifies small changes. This system generates build recipes for file conversion in the correct formats. It is extensible and pluggable, allowing for easy addition of new features.
Internal Linking through Labels: Disseminate offers consistent and easy label creation for internal links to other documents, chapters, sections, figures, and tables. The label formatting is either template-controlled or defined by the user in document headers.
Document Structure: Projects in Disseminate can range from a single document to a complex book consisting of multiple parts and chapters.
Rendering Equations: Disseminate provides tags for rendering equations in LaTeX format, for example, This equation, @eq{y = mx + b}, is inline.
Website Preview through Webserver: Disseminate includes a built-in webserver that allows users to preview their processed document projects.
Multi-format Output: Disseminate supports rendering projects into diverse formats including .html, .pdf, .epub, .txt, and .tex.
Typography and Templates: Disseminate prioritizes producing documents that adhere to good typographical style. It provides templates for textbooks with Tufte formatting, books, novels, reports, and articles.
Advanced Document Inheritance: Entries in a document's header can affect how that document and all its sub-documents are rendered.
Target-Specific Tag Attributes: Tag attributes may include target specifiers to change how a tag is rendered in different target formats. For example, @img[width=80% width.html=40%]{figures/fig1.png}.
Customizable Label Formats: The rendering of label captions and reference links can be customized for a document or for a project in the root document.
Built-in Signals Framework: Processing functions in Disseminate use a built-in ordered signals framework, facilitating the easy insertion of processing steps and the creation of plug-ins.

Disseminate VS Sphinx

While Sphinx is tailored for code documentation, Disseminate is designed for general writing, including books, articles, essays, and reports.

Disseminate employs a straightforward, consistent syntax that's easy to comprehend.
Unlike Sphinx, which uses Make and can overlook document rebuilds, Disseminate features an integrated build system.
This build system of Disseminate is multithreaded and handles dependencies implicitly, eliminating user concerns over converting or building dependencies like images or data.
The structure of Disseminate projects is simple, catering to both single file documents or complex books, with the aim of making document projects user-friendly for non-coders.
Disseminate places importance on typography within its templates, focusing on readability and providing a simplified, unobtrusive navigation. This is in contrast to source code documentation which facilitates navigation between diverse pages and presents potentially intricate text structures.
Lastly, the Disseminate parser is deliberately uncomplicated to encourage contributions from others.

Install on macOS

brew install dissemia/dissemia/disseminate

Install using Pip

pip install disseminate

Usage

Create a project directory

mkdir -p ~/Documents/Disseminate/test-project/src
cd ~/Documents/Disseminate/test-project

Create a root document

echo "@chapter{My First Chapter}" > src/index.dm

Start an internal webserver

dm preview
[2020-04-22 13:36:08 -0500] [58827] [INFO] Goin' Fast @ http://127.0.0.1:8899
[2020-04-22 13:36:08 -0500] [58827] [INFO] Starting worker [58827]

Then head to "http://localhost:8899"