npm package: @mmg-dev/arc42-bridge
Description: A tool to synchronize arc42 documentation from markdown to Confluence
Author: Messe München GmbH
Latest version: 0.9.4

# 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:

```bash
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:

```bash
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:

```bash
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:

```text
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:

```json
"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:**

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

2.  **Install dependencies:**
    ```bash
    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.

    ```bash
    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.

```bash
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: +

```bash
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:

```markdown
## 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 (<td> or <th>) 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.

```markdown
| 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.