How To: Update Arc42 Documentation

Last Updated: May 31, 2026 Difficulty: Beginner Estimated Time: 10–15 minutes

---

Overview

This guide explains how to update or add arc42 architecture documentation and publish it to the CTN Documentation Portal.

The most important thing to understand first: there are two repositories.

Repository	Where	What it is
CNCL-BDI (source)	GitHub: Basic-Data-Infrastructure/CNCL-BDI	The single source of truth for all arc42 docs. You edit content here.
CTN-Documentation (publishing site)	Azure DevOps: DeNoronhaConsulting/CTN Documentation	The Astro + Starlight website that publishes the docs. It does not author content.

⚠️ Do not edit docs/arc42/ inside the CTN-Documentation repo. That folder is generated by the sync step and will be wiped and overwritten the next time anyone runs npm run sync-arc42. Any edit you make there directly will be lost. Edit the docs in CNCL-BDI instead.

How content reaches the live site:

graph LR
    A[Edit docs in CNCL-BDI/docs/arc42] --> B[Push to GitHub]
    B --> C[npm run sync-arc42 in CTN-Documentation]
    C --> D[npm run build  -> dist/]
    D --> E[Commit docs/arc42 + push to Azure DevOps]
    E --> F[Azure Pipeline builds & deploys]
    F --> G[Live site]

Note: This how-to guide itself (and everything under docs/how-to/) is authored directly in the CTN-Documentation repo — only docs/arc42/ is synced from CNCL-BDI.

---

Prerequisites

• ✅ Git access to both repos: CNCL-BDI (GitHub) and CTN-Documentation (Azure DevOps)
• ✅ The two repos checked out as siblings in the same parent folder:

  <parent>/
  ├── CNCL-BDI/            # source content
  └── CTN-Documentation/   # publishing site

  (The sync script looks for ../CNCL-BDI/docs/arc42 by default; override with the ARC42_SOURCE env var.)
• ✅ Node.js ≥ 22.12.0 — required by Astro 6. Node 20 will fail with “not supported by Astro!”. Use nvm use 22 or a Node ≥ 22 install.
• ✅ A text/markdown editor (VS Code, etc.)

---

Document Status Workflow

All arc42 documents use status metadata in frontmatter to track their lifecycle:

Status	Description	When to use
Draft	Initial work	Being written, not ready for review
Review	Ready for feedback	Complete enough for team review
Approved	Finalized	Reviewed and approved
Published	Active version	Live and in use
Archived	Old version	Superseded or no longer relevant

---
status: Published
lastUpdate: 2026-05-31
---

---

Quick Reference

TL;DR — edit in the source repo, sync, build, publish:

# 1. Edit content in the SOURCE repo (CNCL-BDI)
cd ../CNCL-BDI
code docs/arc42/05-building-blocks/ctn-connector.md
git add docs/arc42 && git commit -m "docs: update connector" && git push   # to GitHub

# 2. Sync + build + publish from the PUBLISHING repo (CTN-Documentation)
cd ../CTN-Documentation
nvm use 22          # ensure Node >= 22.12.0
npm run sync-arc42  # copy CNCL-BDI/docs/arc42 -> docs/arc42 (wipe + replace)
npm run build       # prepare-content + astro build -> dist/ (also validates links)
git add docs/arc42 && git commit -m "docs: sync arc42 from CNCL-BDI" && git push  # to Azure DevOps

# 3. Done — the Azure pipeline builds and deploys automatically

---

Step-by-Step Process

Step 1: Edit the content in CNCL-BDI (source of truth)

All arc42 documents live in the CNCL-BDI repo under docs/arc42/:

CNCL-BDI/docs/arc42/
├── ctn-arc42-index.md
├── 00-guidelines/ctn-documentation-guidelines.md
├── 01-introduction/
│   ├── ctn-initiative-overview.md
│   ├── bdi-framework-principles.md
│   └── ctn-terminology-clarification.md
├── 02-constraints/02-constraints.md
├── 03-context/ctn-context.md
├── 04-solution-strategy/ctn-solution-strategy.md
├── 05-building-blocks/
│   ├── ctn-building-blocks.md
│   ├── ctn-connector.md
│   ├── ctn-association-register.md
│   └── ...
├── 06-runtime/ ... 07-deployment/ ... 08-crosscutting/ ...
├── 09-decisions/            # ADRs (00001-…), ADR-TEMPLATE.md, README.md
├── 10-quality/ ... 11-risks/ ... 12-glossary/ ... 13-roadmap/

File naming: descriptive-title.md, lowercase-with-hyphens, no date prefixes. Place each file in the correct numbered chapter directory — the website sidebar is autogenerated from these directories.

Editing an existing document:

1. Open the file in CNCL-BDI, e.g. docs/arc42/05-building-blocks/ctn-connector.md.
2. Make your changes in Markdown.
3. Update the frontmatter status and lastUpdate as appropriate.
4. Save.

Creating a new document:

---
status: Draft
lastUpdate: 2026-05-31
---

# New Component Architecture

## Overview

Your content here...

Drop it in the relevant chapter directory — it appears in the sidebar automatically after the next build.

Step 2: Commit & push the source repo (GitHub)

cd ../CNCL-BDI
git add docs/arc42
git commit -m "docs: add connector retry semantics"
git push        # pushes to GitHub (Basic-Data-Infrastructure/CNCL-BDI)

This makes your edit the canonical version. (It is also what feeds GitHub Discussions–based comments on the site, via giscus.)

Step 3: Sync into the publishing repo

From the CTN-Documentation repo, copy the latest arc42 content in:

cd ../CTN-Documentation
nvm use 22                 # Astro requires Node >= 22.12.0
npm install                # first time only / after dependency changes
npm run sync-arc42

sync-arc42 runs scripts/sync-arc42.cjs, which:

• copies ../CNCL-BDI/docs/arc42 → docs/arc42, wiping the destination first so deleted/renamed upstream files don’t leave stale copies;
• can be pointed elsewhere via the ARC42_SOURCE env var;
• auto-skips when the source isn’t present (e.g. in CI) and uses the already-committed docs/arc42.

You should see ✅ Synced N markdown file(s) into docs/arc42.

Step 4: Build and preview locally

# One-off production build (also validates all internal links)
npm run build

# …or run a live dev server with hot reload
npm run dev      # then open the printed http://localhost:4321 URL

# …or preview the built output
npm run preview

npm run build runs prepare-content (stages docs/arc42 + docs/how-to into src/content/docs/, builds the splash homepage and “recently updated” cards) and then astro build, producing static HTML in dist/. A healthy build ends with something like:

[build] N page(s) built in …
· All internal links are valid. ·
[build] Complete!

If the link validator reports broken links, fix them in CNCL-BDI, then re-run sync-arc42 and build.

Step 5: Commit the synced docs & push (publish)

The Azure pipeline only checks out the CTN-Documentation repo, so the synced docs/arc42 content must be committed here for the live site to update.

git add docs/arc42
git commit -m "docs: sync arc42 from CNCL-BDI"
git push        # pushes to Azure DevOps (DeNoronhaConsulting/CTN Documentation)

Step 6: Automatic deployment

After the push to main, the Azure DevOps pipeline (azure-pipelines.yml) automatically:

1. ✅ Installs Node 22.x and dependencies
2. ✅ Runs npm run build (in CI the sync is skipped — it builds from the committed docs/arc42)
3. ✅ Copies staticwebapp.config.json into dist/
4. ✅ Deploys dist/ to the Azure Static Web App

Verify deployment (~4–5 minutes):

1. Check the build at the pipeline (link below).
2. Visit the portal: https://docs.preview.inlandbase.com
3. Confirm your page appears in the sidebar and at its URL. Starlight URLs are lowercase, directory-style, with no .html, e.g. https://docs.preview.inlandbase.com/arc42/05-building-blocks/ctn-connector/

---

Markdown Best Practices

Headings

# H1 — Page title (use once per document)
## H2 — Major section
### H3 — Subsection

Links

Prefer relative links between docs; the build validates internal links.

[Link text](https://example.com)
[Another arc42 page](../05-building-blocks/ctn-connector.md)

Code blocks

```typescript
interface User { id: string; name: string; }
```

Tables

| Feature | Status | Priority |
|---------|--------|----------|
| Auth    | ✅ Done | High     |

Mermaid diagrams

Mermaid is rendered at build time via the astro-mermaid integration — just use a fenced mermaid block:

```mermaid
graph LR
    A[Client] --> B[API Gateway] --> C[Service] --> D[Database]
```

---

Troubleshooting

Build fails with “Node.js … is not supported by Astro!”

Astro 6 requires Node ≥ 22.12.0. Run node --version; if it’s older, nvm use 22 (or install Node 22+).

sync-arc42 reports “arc42 source not found”

The CNCL-BDI repo isn’t a sibling of CTN-Documentation, or is checked out elsewhere. Either place it at ../CNCL-BDI, or set the source explicitly:

ARC42_SOURCE=/absolute/path/to/CNCL-BDI/docs/arc42 npm run sync-arc42

My edit to docs/arc42 in CTN-Documentation disappeared

Expected — that folder is overwritten by sync-arc42. Make the edit in CNCL-BDI and re-sync.

Document doesn’t appear in the sidebar

1. Confirm the file is in the correct numbered chapter directory under CNCL-BDI’s docs/arc42/ (the sidebar autogenerates per directory).
2. Confirm you ran npm run sync-arc42 and then npm run build.
3. Check the build output for errors.

Build reports broken internal links

The starlight-links-validator plugin fails the build on broken internal links. Fix the link in CNCL-BDI, re-sync, rebuild.

Build fails in Azure DevOps

1. Check the pipeline logs (link below).
2. Reproduce locally with npm run build.
3. Look for Markdown/link errors or missing dependencies.

---

Quick Tips

DO ✅

• Edit arc42 content in CNCL-BDI, never in CTN-Documentation’s docs/arc42
• Keep the two repos as siblings
• Use Node ≥ 22.12.0
• Run sync-arc42 → build and check links before committing
• Use lowercase-with-hyphens.md filenames in the right chapter directory
• Keep status and lastUpdate frontmatter current

DON’T ❌

• Don’t edit the synced docs/arc42 in the publishing repo
• Don’t use date prefixes in filenames
• Don’t push to Azure DevOps without first syncing the latest source
• Don’t expect content changes to publish from a CNCL-BDI push alone — you must sync + commit + push in CTN-Documentation

---

Related Documentation

• arc42 Template — the architecture documentation standard
• Markdown Guide — Markdown syntax reference
• Mermaid Documentation — diagram syntax
• Starlight — the docs framework this site is built on
• Azure DevOps build pipeline — https://dev.azure.com/DeNoronhaConsulting/CTN%20Documentation/_build

---

Summary

1. ✏️ Edit arc42 docs in CNCL-BDI (docs/arc42/) and push to GitHub
2. 🔄 Sync into CTN-Documentation: npm run sync-arc42
3. 🧪 Build & preview: npm run build (or npm run dev) — fix any broken links
4. 💾 Commit & push the synced docs/arc42 to Azure DevOps
5. ⏱️ Wait ~4–5 min for the pipeline to build and deploy
6. ✅ Verify on https://docs.preview.inlandbase.com