Overview

Composer is a simple but powerful CMS based on [Pandoc], [Bootstrap] and [GNU Make]. It is a document and website build system that processes directories or individual files in [Markdown] format.

Traditionally, CMS stands for Content Management System. Composer is designed to be a Content Make System. Written content is vastly easier to manage as plain text, which can be crafted with simple editors and tracked with revision control. However, professional documentation, publications, and websites require formatting that is dynamic and feature-rich.

[Pandoc] is an extremely powerful document conversion tool, and is a widely used standard for processing [Markdown] into other formats. While it has reasonable defaults, there are a large number of options, and additional tools are required for some formats and features.

Composer consolidates all the necessary components, simplifies the options, and prettifies the output formats, all in one place. It also serves as a build system, so that large repositories can be managed as documentation archives or published as [Static Websites].

Quick Start

Use make help to get started:

make [-f .../Makefile] [variables] <filename>.<extension>
make [-f .../Makefile] [variables] <target>

Create documents from source [Markdown] files (see Formatting Variables):

make README.html
make Composer-v3.1.Manual.html c_list="README.md LICENSE.md"

Save a persistent configuration (see [Recommended Workflow] and [Configuration Settings]):

make template >.composer.mk
$EDITOR .composer.mk
    override COMPOSER_TARGETS := .targets Composer-v3.1.Manual.html
    override Composer-v3.1.Manual.html := README.md LICENSE.md
make clean
make all

Recursively install and build an entire directory tree (see [Recommended Workflow]):

cd .../documents
mv .../composer .Composer
make -f .Composer/Makefile install-all
make all-all

See help-all for full details and additional targets.

Principles

The guiding principles of Composer:

• All source files in readable plain text
• Professional output, suitable for publication
• Minimal dependencies, and entirely command-line driven
• Separate content and formatting; writing and publishing are independent
• Inheritance and dependencies; global, tree, directory and file overrides
• Fast; both to initiate commands and for processing to complete

Direct support for key document types (see [Document Formatting]):

• [Static Websites]
• [HTML]
• [PDF]
• [EPUB]
• [Reveal.js Presentations]
• [Microsoft Word & PowerPoint]

Requirements

Composer has almost no external dependencies. All needed components are integrated directly into the repository, including [Pandoc] and [YQ]. Composer does require a minimal command-line environment based on [GNU] tools, particularly [GNU Make], which is standard for all [GNU/Linux] systems. The [Windows Subsystem for Linux] for Windows and [MacPorts] for macOS both provide suitable environments.

The one large external requirement is [TeX Live], and it can be installed using the package managers of each of the above systems. It is only necessary for creating [PDF] files.

Below are the versions of the components in the repository, and the tested versions of external tools for this iteration of Composer. Use [check] to validate your system.

[Markdown Viewer] is included both for its CSS stylesheets, and for real-time rendering of [Markdown] files as they are being written. To install, follow the instructions in the README.md.

[Google Firebase] is only necessary for uploading via the [export-all] and [export-force] targets. Binaries are included in the repository, but do not seem to work with all versions of their respective operating systems. If the included binary fails, use +update-firebase-tools to build a local version (see [+update-*]).

The versions of the integrated repositories can be changed, if desired (see [Repository Versions]).

Formatting Variables

• Other [c_type] values will be passed directly to [Pandoc]
• Special [c_css] values:
  • css_alt = Use the alternate default stylesheet
  • 0 = Revert to the [Pandoc] default
• Special [c_toc] value: 0 = List all headers, and number sections
• Special [c_level] value: 0 = Varies by [c_type] (see [c_level])
• An empty [c_margin] value enables individual margins:
  • c_margin_top ~ mt
  • c_margin_bottom ~ mb
  • c_margin_left ~ ml
  • c_margin_right ~ mr

Control Variables

• [MAKEJOBS] ~ c_jobs ~ J
• [COMPOSER_DEBUGIT] ~ c_debug ~ V
• [COMPOSER_DOCOLOR] ~ c_color ~ C
• (makejobs) = empty is disabled / number of threads / 0 is no limit
• (debugit) = empty is disabled / any value enables / 0 is full tracing
• (keeping) = empty is none / number to keep / 0 is no limit
• (boolean) = empty is disabled / any value enables

Helper Variables

• (mk) = configurable in .composer.mk
• (yml) = configurable in .composer.yml

Primary Targets

Additional Targets

Command Examples

Create documents from source [Markdown] files (see Formatting Variables):

make README.html
make Composer-v3.1.Manual.html c_list="README.md LICENSE.md"

Save a persistent configuration (see [Recommended Workflow] and [Configuration Settings]):

make template >.composer.mk
$EDITOR .composer.mk
    override COMPOSER_TARGETS := .targets Composer-v3.1.Manual.html
    override Composer-v3.1.Manual.html := README.md LICENSE.md
make clean
make all

Recursively install and build an entire directory tree (see [Recommended Workflow]):

cd .../documents
mv .../composer .Composer
make -f .Composer/Makefile install-all
make all-all

See help-all for full details and additional targets.

Go Make A Thing

Happy Making!