Monorepo Visibility: Building Auto-Updating Status Dashboards with Markdown Transclusion

Managing a monorepo with dozens of packages is challenging enough without the added complexity of keeping stakeholders informed about each package's status. Tech leads spend hours in meetings explaining which packages are stable, which are in beta, and which have blocking issues. Platform teams struggle to maintain centralized documentation that's perpetually out of date.

What if your status dashboard could update itself?

The Monorepo Visibility Problem

In a typical monorepo, status information is scattered across multiple locations: Jira tickets, Slack channels, README files, and team meetings. This fragmentation creates several problems:

• Information silos: Each team knows their package status, but cross-team visibility is poor
• Stale documentation: Centralized dashboards require manual updates that inevitably fall behind
• Context switching: Managers jump between files and tools to get a complete picture
• Duplicate effort: Teams maintain both local and centralized status documents

The solution isn't more tooling or another dashboard platform. It's leveraging what developers already do well: maintaining documentation close to their code.

The Transclusion Pattern for Monorepo Dashboards

Transclusion is a powerful concept where content from one document is automatically embedded in another. Unlike copy-paste, transcluded content stays linked to its source. When the source changes, every document that includes it updates automatically.

Here's the pattern: each package maintains its own STATUS.md file with version info, health metrics, and recent changes. A central DASHBOARD.md file uses transclusion syntax to pull all these status files into a single view.

Let's see this in action with a real-world example.

Case Study: The ShopFlow E-Commerce Platform

ShopFlow is an e-commerce platform built as a monorepo with four core packages:

Package	Purpose	Current Status
@shopflow/auth	Authentication & user sessions	Stable
@shopflow/payments	Payment processing & subscriptions	Beta
@shopflow/inventory	Stock management & warehousing	Stable
@shopflow/notifications	Email, SMS, push notifications	Release Candidate

Each package team maintains their own STATUS.md with consistent structure. Here's what the auth package's status looks like:

### @shopflow/auth

| | |
|---|---|
| **Version** | v2.4.1 |
| **Status** | Stable |
| **Build** | Passing |
| **Coverage** | 94% |

**Recent Activity**
- [x] OAuth 2.0 PKCE flow implemented
- [x] Session refresh token rotation
- [x] Rate limiting on login endpoints
- [ ] WebAuthn/passkey support (v2.5.0)

**Dependencies**: 0 critical vulnerabilities

**Maintainers**: @alice, @bob

This file lives at packages/auth/STATUS.md, right next to the code. The team updates it as part of their normal workflow.

Creating the Aggregated Dashboard

The magic happens in the central DASHBOARD.md file. Using transclusion syntax, it pulls in all package statuses:

# ShopFlow Platform Dashboard

> Real-time status aggregated from all packages

## Platform Health Overview

| Metric | Value |
|--------|-------|
| Total Packages | 4 |
| Stable | 2 |
| Beta | 1 |
| Release Candidate | 1 |

## Package Status

![[packages/auth/STATUS.md]]

---

![[packages/payments/STATUS.md]]

---

![[packages/inventory/STATUS.md]]

---

![[packages/notifications/STATUS.md]]

When you open this dashboard in a markdown reader that supports transclusion, you see a complete, unified view of all package statuses. The content isn't copied; it's dynamically included from the source files.

The Live Update Workflow

Here's where transclusion transforms your project management workflow:

1. Developer completes a feature: The payments team ships Buy Now Pay Later support
2. Team updates their STATUS.md: They change the checkbox from [ ] to [x]
3. Dashboard updates automatically: Anyone viewing DASHBOARD.md sees the change immediately

No manual syncing. No forgetting to update the central doc. No status meetings where information is already stale.

Consider this scenario: QA finds a critical bug in the notifications package's release candidate. The team adds a "Known Issues" section to their STATUS.md:

**Known Issues**
- Critical: Push notifications failing on iOS 17.2 (#891)
- Blocking v2.0.0 release until resolved

Instantly, the central dashboard reflects this blocker. Tech leads and stakeholders see the issue without anyone sending an email or scheduling a meeting.

Extending the Pattern

The monorepo dashboard pattern works for many use cases beyond package status:

• Release readiness checklists: Aggregate pre-release checks from each team
• Architecture Decision Records (ADR) indexes: Maintain ADRs in each package, index them centrally
• API documentation aggregation: Pull API summaries from each service into a unified catalog
• Multi-team project tracking: Each team maintains their sprint status, PMs see the rollup
• Dependency audit dashboards: Track security vulnerabilities across all packages

Best Practices for STATUS.md Files

To make this pattern work effectively:

1. Standardize the format: Use consistent headers and sections across all packages
2. Keep it scannable: Use tables and checklists over prose paragraphs
3. Include metadata: Version, status, maintainers, and build status at a glance
4. Link to details: Reference issues, changelogs, and documentation for deeper dives
5. Update as part of workflow: Make status updates part of your PR process

Try It Yourself

Ready to bring monorepo visibility to your team? Ohai Markdown Reader supports transclusion out of the box, with live reload that updates your dashboard as files change.

1. Create a STATUS.md in each package with consistent structure
2. Build your DASHBOARD.md with transclusion embeds
3. Open the dashboard in Ohai Markdown Reader
4. Watch it update in real-time as your team works

Stop chasing status updates across Slack channels and stale wikis. Let your documentation maintain itself.

Download Ohai Markdown Reader and start building your auto-updating monorepo dashboard today.

---

Have questions about implementing transclusion dashboards in your organization? Reach out to us on Twitter or GitHub. We'd love to hear how you're using this pattern.