Business Plan Compilation Workflow
Summary
An automated build process for synthesizing the Sokrates business plan from modular markdown sources into professional formats. The workflow utilizes a Justfile to orchestrate pandoc commands, generating both a unified markdown file and a formatted .docx document with a table of contents and metadata.
Details
The Sokrates business plan is maintained as a collection of modular markdown files located within the docs/business-plan/ directory. To facilitate professional distribution and internal review, a compilation process was established to transform these fragments into cohesive documents.
Tooling and Configuration
The workflow is managed via a Justfile (using the just command runner). This file integrates standard project commands (such as pnpm tasks) with specific recipes for document generation. The primary transformation engine is Pandoc, which handles the conversion from Markdown to Word (.docx) format.
The compilation process performs the following steps:
- Concatenation: All markdown files in the business plan directory are merged in a specific order. The source files consistently use
##(H2) as their top-level headings, allowing the build process to prepend a single#(H1) title without breaking the document hierarchy. - Metadata Injection: A YAML frontmatter block is dynamically generated and prepended to the concatenated file. This block includes the document title, author information, and language settings (
lang: is-ISfor Icelandic, though Pandoc may default to English for certain table labels). - Formatting: The Pandoc configuration is set to generate a Table of Contents (TOC) and apply section numbering up to three levels deep.
- Output Management: All generated artifacts are placed in a
docs/business-plan/dist/directory. This directory is explicitly excluded from version control via.gitignoreto prevent build artifacts from cluttering the repository.
Just Recipes
The following recipes are available for managing the business plan:
just bp: The master command that executes the full compilation, producing both the concatenated.mdand the final.docxfile.just bp-md: Generates only the unified markdown file with the injected YAML frontmatter.just bp-docx: Generates the Word document (depends on the markdown output).just bp-clean: Removes thedist/directory and all compiled artifacts.
Technical Considerations
During the implementation of this process, it was noted that Pandoc might issue cosmetic warnings regarding Icelandic translations for specific labels (like “Table”). These were deemed non-critical for the initial business plan drafts. The system is designed to be extensible, allowing for a custom reference document (reference.docx) to be added later if specific corporate styling or branding is required.