# diecieventi/system-markdown-alternate architecture

> Architecture diagram of the GitHub repository diecieventi/system-markdown-alternate, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/diecieventi/system-markdown-alternate
- Repository: https://github.com/diecieventi/system-markdown-alternate

## Overview

System Markdown Alternate is a WordPress plugin that serves post-derived Markdown at `.md` URLs and through content negotiation. Its main workflow resolves and validates a request, renders cleaned post content, adds configured metadata, converts the result, and returns it with HTTP representation and cache handling. Separate branches cover settings, discovery, builder/ACF integrations, and optional traffic and LiteSpeed features. The README documents capabilities beyond the sampled excerpts; those branches are included where paths are supported, without asserting unverified internal call details.

Main entry points: [`system-markdown-alternate/src/MarkdownController.php`](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MarkdownController.php) (Markdown controller), [`system-markdown-alternate/src/ContentRenderer.php`](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/ContentRenderer.php) (Content renderer), [`system-markdown-alternate/src/MetadataBuilder.php`](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MetadataBuilder.php) (Front matter), [`system-markdown-alternate/src/AdminSettings.php`](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/AdminSettings.php) (Admin settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_request["Request and response"]
  node_plugin["Plugin bootstrap"]
  node_controller["Markdown controller"]
  node_negotiator["Accept negotiation"]
  node_support["Post eligibility<br/>[PostSupport.php]"]
  node_cache[("Markdown cache<br/>[Cache.php]")]
end

subgraph group_content["Content production"]
  node_renderer["Content renderer"]
  node_converter["Markdown conversion"]
  node_metadata["Front matter"]
  node_meta["Custom fields<br/>[MetaFields.php]"]
  node_builderdetector["Builder detection"]
  node_builderadapter["Builder adapters<br/>[BuilderAdapter.php]"]
  node_bricks["Bricks rendering<br/>[BricksAdapter.php]"]
end

subgraph group_control["Settings and discovery"]
  node_settings["Admin settings<br/>[AdminSettings.php]"]
  node_shortcodes["Discovery shortcodes<br/>[Shortcodes.php]"]
  node_actions["Markdown actions"]
end

subgraph group_integrations["Integrations and operations"]
  node_acf["ACF integration<br/>[AcfIntegration.php]"]
  node_dynamic["Dynamic tags<br/>[DynamicTags.php]"]
  node_woocommerce["WooCommerce compatibility"]
  node_hits[("Hit counter<br/>[HitCounter.php]")]
  node_litespeed["LiteSpeed compatibility"]
end

node_client(("HTTP client"))
node_wordpress["WordPress runtime"]

node_client -->|"sends request"| node_wordpress
node_wordpress -->|"loads plugin"| node_plugin
node_plugin -->|"boots"| node_controller
node_client -->|"requests Markdown"| node_controller
node_controller -->|"checks Accept"| node_negotiator
node_controller -->|"checks eligibility"| node_support
node_controller -->|"reads or writes"| node_cache
node_controller -->|"builds content"| node_renderer
node_controller -->|"builds front matter"| node_metadata
node_renderer -->|"renders blocks"| node_wordpress
node_renderer -->|"detects builder"| node_builderdetector
node_builderdetector -->|"selects adapter"| node_builderadapter
node_builderadapter -->|"dispatches Bricks posts"| node_bricks
node_renderer -->|"converts HTML"| node_converter
node_metadata -->|"reads configured fields"| node_meta
node_metadata -.->|"uses ACF values"| node_acf
node_controller -->|"returns representation"| node_client
node_controller -.->|"records request"| node_hits
node_settings -->|"registers settings"| node_wordpress
node_settings -->|"invalidates cache"| node_cache
node_shortcodes -->|"generates Markdown URL"| node_controller
node_shortcodes -->|"renders actions"| node_actions
node_dynamic -.->|"provides Markdown URL"| node_controller
node_woocommerce -->|"excludes commerce pages"| node_support
node_litespeed -.->|"signals cache behavior"| node_wordpress

click node_plugin "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/system-markdown-alternate.php"
click node_controller "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MarkdownController.php"
click node_negotiator "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/AcceptNegotiator.php"
click node_support "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/PostSupport.php"
click node_cache "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/Cache.php"
click node_renderer "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/ContentRenderer.php"
click node_converter "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MarkdownConverter.php"
click node_metadata "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MetadataBuilder.php"
click node_meta "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MetaFields.php"
click node_builderdetector "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/BuilderDetector.php"
click node_builderadapter "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/BuilderAdapter.php"
click node_bricks "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/BricksAdapter.php"
click node_settings "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/AdminSettings.php"
click node_shortcodes "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/Shortcodes.php"
click node_actions "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MarkdownActions.php"
click node_acf "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/AcfIntegration.php"
click node_dynamic "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/DynamicTags.php"
click node_woocommerce "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/WooCommerceCompat.php"
click node_hits "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/HitCounter.php"
click node_litespeed "https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/LiteSpeedCompat.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin,node_controller,node_negotiator,node_support,node_cache,node_client toneBlue
class node_renderer,node_converter,node_metadata,node_meta,node_builderdetector,node_builderadapter,node_bricks toneAmber
class node_settings,node_shortcodes,node_actions toneMint
class node_acf,node_dynamic,node_woocommerce,node_hits,node_litespeed toneRose
class node_wordpress toneIndigo
```

## Components

### Request and response

- [Plugin bootstrap](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/system-markdown-alternate.php): `system-markdown-alternate/system-markdown-alternate.php`
- [Markdown controller](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MarkdownController.php): `system-markdown-alternate/src/MarkdownController.php`
- [Accept negotiation](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/AcceptNegotiator.php): `system-markdown-alternate/src/AcceptNegotiator.php`
- [Post eligibility](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/PostSupport.php): `system-markdown-alternate/src/PostSupport.php`
- [Markdown cache](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/Cache.php): `system-markdown-alternate/src/Cache.php`

### Content production

- [Content renderer](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/ContentRenderer.php): `system-markdown-alternate/src/ContentRenderer.php`
- [Markdown conversion](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MarkdownConverter.php): `system-markdown-alternate/src/MarkdownConverter.php`
- [Front matter](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MetadataBuilder.php): `system-markdown-alternate/src/MetadataBuilder.php`
- [Custom fields](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MetaFields.php): `system-markdown-alternate/src/MetaFields.php`
- [Builder detection](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/BuilderDetector.php): `system-markdown-alternate/src/BuilderDetector.php`
- [Builder adapters](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/BuilderAdapter.php): `system-markdown-alternate/src/BuilderAdapter.php`
- [Bricks rendering](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/BricksAdapter.php): `system-markdown-alternate/src/BricksAdapter.php`

### Settings and discovery

- [Admin settings](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/AdminSettings.php): `system-markdown-alternate/src/AdminSettings.php`
- [Discovery shortcodes](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/Shortcodes.php): `system-markdown-alternate/src/Shortcodes.php`
- [Markdown actions](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/MarkdownActions.php): `system-markdown-alternate/src/MarkdownActions.php`

### Integrations and operations

- [ACF integration](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/AcfIntegration.php): `system-markdown-alternate/src/AcfIntegration.php`
- [Dynamic tags](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/DynamicTags.php): `system-markdown-alternate/src/DynamicTags.php`
- [WooCommerce compatibility](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/WooCommerceCompat.php): `system-markdown-alternate/src/WooCommerceCompat.php`
- [Hit counter](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/HitCounter.php): `system-markdown-alternate/src/HitCounter.php`
- [LiteSpeed compatibility](https://github.com/diecieventi/system-markdown-alternate/blob/main/system-markdown-alternate/src/LiteSpeedCompat.php): `system-markdown-alternate/src/LiteSpeedCompat.php`

### Other components

- **HTTP client**
- **WordPress runtime**

## Connections

- HTTP client → WordPress runtime: sends request
- WordPress runtime → Plugin bootstrap: loads plugin
- Plugin bootstrap → Markdown controller: boots
- HTTP client → Markdown controller: requests Markdown
- Markdown controller → Accept negotiation: checks Accept
- Markdown controller → Post eligibility: checks eligibility
- Markdown controller → Markdown cache: reads or writes
- Markdown controller → Content renderer: builds content
- Markdown controller → Front matter: builds front matter
- Content renderer → WordPress runtime: renders blocks
- Content renderer → Builder detection: detects builder
- Builder detection → Builder adapters: selects adapter
- Builder adapters → Bricks rendering: dispatches Bricks posts
- Content renderer → Markdown conversion: converts HTML
- Front matter → Custom fields: reads configured fields
- Front matter → ACF integration: uses ACF values
- Markdown controller → HTTP client: returns representation
- Markdown controller → Hit counter: records request
- Admin settings → WordPress runtime: registers settings
- Admin settings → Markdown cache: invalidates cache
- Discovery shortcodes → Markdown controller: generates Markdown URL
- Discovery shortcodes → Markdown actions: renders actions
- Dynamic tags → Markdown controller: provides Markdown URL
- WooCommerce compatibility → Post eligibility: excludes commerce pages
- LiteSpeed compatibility → WordPress runtime: signals cache behavior