arc42-bridge

A Node.js tool to automatically publish and synchronize arc42 software architecture documentation from local Markdown files to a Confluence space.

This tool is designed to bridge the gap between "docs-as-code" stored in a Git repository and the collaborative environment of Confluence. It renders diagrams, handles versioning based on Git branches, and ensures that your Confluence documentation is always up-to-date with your repository.

Key Features

• Markdown to Confluence: Converts arc42-structured Markdown files into Confluence-compatible HTML.
• Diagram Rendering: Automatically renders plantuml code blocks into SVG images.
• Attachment Handling: Uploads rendered PlantUML diagrams as attachments to the corresponding Confluence page and embeds them.
• Intelligent Synchronization:
  • Compares local files with existing Confluence pages to identify changes.
  • Dynamically generates a 99_diagrams page in-memory, which collects all PlantUML diagrams from the documentation for a central overview.
  • Creates new pages for new Markdown files.
  • Updates existing pages when changes are detected.
  • Deletes obsolete pages if the corresponding Markdown file has been removed.
• Branch-based Versioning:
  • Publishes from the master branch as „to-be“ (planned) documentation.
  • Optionally publishes from the prod branch as "as-is" (current state) documentation, if configured.
  • Uses different parent pages in Confluence to separate the two versions.
• Dynamic Metadata: Automatically adds a "last modified" date (from Git history) and other metadata to each page.
• Flexible Configuration: All settings are easily configurable via a .env file.

Quick Start: Create a New Project

The easiest way to set up a new architecture documentation project from scratch.

1. Initialize Project & Install

Create a folder, initialize package.json, and install the bridge:

mkdir arc42-myproject && cd arc42-myproject
pnpm init
pnpm add -D @mmg-dev/arc42-bridge

2. Scaffold Structure

Run the initialization command to create the required directory structure and template files:

pnpm exec arc42-bridge init

This will:

• Create the arc42/ directory with template Markdown files and PlantUML styles.
• Create a .env file from the example.

3. Configure

Open the generated .env file and enter your Confluence credentials (CONFLUENCE_USER, CONFLUENCE_PASSWORD, etc.).

Manual Integration (Existing Project)

If you want to add arc42-bridge to an existing application (e.g., arc42-web or arc42-vmp) without using the init command.

1. Installation

Install the package as a development dependency:

pnpm add -D @mmg-dev/arc42-bridge

2. Directory Structure (Convention over Configuration)

The tool strictly requires Markdown files to be located in a folder named arc42 at the root of the host project:

arc42-myproject/
├── arc42/
│   ├── styles/
│   │   └── mmg-web-tobe.puml
│   ├── 01_introduction_and_goals.md
│   ├── 02_architecture_constraints.md
│   └── ...
├── package.json
└── .env

3. NPM Script

Add a script to the package.json of the host project:

"scripts": {
  "docs:publish": "arc42-bridge"
}

Prerequisites

If you run the tool locally (whether as an installed package or within the bridge repo itself), you need:

• Node.js (v18 or later recommended)
• Git

Setup for Development (Contributor)

The following steps are only necessary if you want to work on the code of the bridge itself.

1. Clone the repository:

   git clone <your-repo-url>
   cd <your-repo-name>

2. Install dependencies:

   pnpm install

Editor Setup

For an optimal development experience when editing the architecture documentation, we strongly recommend using Visual Studio Code with the following extensions:

• PlantUML (by jebbs): This extension provides syntax highlighting for PlantUML code blocks and the ability to generate live previews of your diagrams in a separate window (Alt+D). This is extremely helpful for writing and debugging complex diagrams.

• Markdown PlantUML Preview (by myml): This extension enhances the built-in Markdown preview of VS Code. It correctly renders the embedded PlantUML diagrams directly within the standard preview of the Markdown file (Ctrl+Shift+V or Cmd+Shift+V). This gives you a live preview of the entire document as you type.

Together, these two extensions provide a seamless experience for working with the architecture documentation.

Primary Workflow (Automated via CI/CD)

The standard process for updating the architecture documentation is fully automated via a Bamboo pipeline. Manual execution of the script is not part of the normal workflow.

1. Work in a Feature Branch: Create a new Git branch for your changes.
2. Edit Documentation: Modify the Markdown files in the arc42 directory as needed. You can use the recommended editor setup for a live preview.
3. Create a Pull Request: Once your changes are complete, create a pull request to merge your feature branch into:
   • master to update the "to-be" (planned) documentation.
   • prod to update the „as-is“ (current state) documentation.
4. Automatic Synchronization: After the pull request is reviewed and merged, the Bamboo pipeline automatically triggers the arc42-bridge tool. The script applies your changes to the corresponding space in Confluence.

Optional: Applying Changes Locally

The following steps are only necessary if you want to run the synchronization script on your local machine for testing or development purposes. This is not the standard workflow.

Configuration

1. Create your environment file: Copy the example file .env.example to a new file named .env in the project root.

   cp .env.example .env

2. Fill in your configuration: Open the .env file and replace the placeholder values with your actual Confluence details:

   • CONFLUENCE_USER: Your email address for Confluence.
   • CONFLUENCE_PASSWORD: Your Confluence API token.
   • CONFLUENCE_BASE: The base URL of your Confluence instance (e.g., https://your-instance.atlassian.net/wiki).
   • CONFLUENCE_SPACE_KEY: The key of the target space in Confluence.
   • CONFLUENCE_PARENT_ID_TOBE: (Required) The page ID for the „to-be“ (planned) documentation.
   • CONFLUENCE_PARENT_ID_ASIS: (Optional) The page ID for the „as-is“ (current state) documentation. If this is not set, publications from the prod branch will be skipped.

Applying Changes (Running the Synchronization)

To apply your local changes to Confluence, run the synchronization script from the project root. This will compare your local files to the remote pages and apply any necessary creations, updates, or deletions.

pnpm prod

The script will automatically detect the current Git branch and publish the documentation to the corresponding parent page in Confluence.

Forcing a Full Republish

In some cases, you might want to force the script to republish all pages, regardless of whether they have changed locally. This can be useful after changes to the script's rendering logic or templates. To do this, use the --force-all flag: +

pnpm prod --force-all

How It Works

1. Analysis: The script determines the current Git branch and reads all local .md files as well as the existing Confluence pages under the configured parent page.
2. Comparison (Diff): It compares the local and remote states to determine which pages need to be created, updated, or deleted.
3. Dynamic Page Generation: Before execution, the script performs an additional step:
   • Only if there are other changes (pages to be created, updated, or deleted), the script scans all local .md files for plantuml code blocks.
   • It then creates a new virtual page in memory, 99_diagrams.md.
   • This page is populated with all found diagrams, each preceded by its original chapter headline and modified to use !theme plain for a black-and-white rendering. This virtual page is then added to the list of pages to be synchronized. If there are no other changes, this step is skipped to avoid unnecessary updates.
4. Execution:
   • Delete: Obsolete pages are removed from Confluence.
   • Create & Update: For each page to be created or updated: a. plantuml blocks are rendered into themed SVGs for Confluence. b. The remaining Markdown content is converted to HTML. c. The page is created or updated in Confluence. d. The SVG images are uploaded as attachments. e. The page content is finalized to display the attachments as embedded images.

Conventions

• Branching: The script relies on a master branch for development ("to-be") and a prod branch for production ("as-is").
• Directory Structure: All arc42 Markdown files must be located in the ./arc42 directory.
• System Key: The systemKey used in Confluence page titles is automatically derived from the repository's directory name (e.g., a directory named arc42-web results in a systemKey of web). Page titles for the "to-be" documentation are formatted as {base-title}_{systemKey} (e.g., 01_introduction_and_goals_web). Page titles for the optional "as-is" documentation are formatted as {base-title}_{systemKey}_asis.
• Work-in-Progress Flag: You can add a comment <!-- wip=true --> at the top of a Markdown file. The script will add a "Work in Progress" banner to the corresponding Confluence page.

Marking Planned Content (tobe=true)

In addition to the wip=true marker, which flags an entire page as „Work in Progress“, there is the <!-- tobe=true --> marker. This is used to mark individual sections within a page as „planned“ or „future“.

Usage:

Place the comment directly under a heading in your Markdown document:

## My Planned Concept {#my-concept}

<!-- tobe=true -->

This text describes a concept that has not yet been implemented.

Result in Confluence:

The arc42-bridge tool recognizes this marker and automatically inserts a green box (a Confluence panel) at this location, which designates the section as „Planned“. This is useful for documenting future architectural decisions or scenarios without marking the entire page as a draft.

Styling Table Cells

You can apply custom background and text colors to individual table cells ( or ) to highlight specific information, such as in a RACI matrix. Usage: + +Place an HTML comment inside the table cell you want to style. The comment can contain bg for the background color and text for the text color.

| Header 1                                                                   | Header 2                                          |
| -------------------------------------------------------------------------- | ------------------------------------------------- |
| Normal Cell                                                                | A cell with a blue background <!-- bg:#b3d4ff --> |
| A cell with a red background and white text <!-- bg:#ff8f73,text:white --> | Just another cell                                 |

Syntax:

• bg:[color]: Sets the background color. You can use any valid hex color code (e.g., #ff8f73) or a named color.
• text:[color]: Sets the text color. Currently, white and black are supported. The properties can be in any order and are typically separated by a comma. The script will parse the comment and apply the corresponding styles to the cell in Confluence.