Why Markdown?

Central Set makes a deliberate choice:

Markdown is not just for documentation.
It is a first-class interface layer.

Markdown is:

  • Human-readable
  • Version-control friendly
  • Self-documenting
  • Syntax-aware
  • Multi-language capable
  • And naturally LLM-compatible

It bridges humans, systems, and AI.

1. Self-Documenting by Design

Markdown forces clarity.

Unlike proprietary dashboard builders or visual workflow tools, Markdown:

  • Is readable without the platform
  • Explains itself
  • Travels with the project
  • Lives inside version control
  • Can be diffed, reviewed, and audited

A Markdown dashboard or ETLX workflow is:

  • Not hidden in a UI state
  • Not buried in a database blob
  • Not trapped inside a proprietary tool

It is plain text.

And plain text scales.

2. Multiple Languages, One File

Markdown allows multiple languages to coexist in the same document.

Inside a single file, you can embed:

  SELECT *
FROM contracts
WHERE status = 'ACTIVE';
  
  def transform(df):
    return df.groupby("segment").sum()
  
  pipeline:
  source: postgres
  target: duckdb
  
  type Contract struct {
    ID     int64
    Amount float64
}

This means:

  • SQL
  • YAML
  • JSON
  • HTML
  • …

Can all live in the same structured document.

And each block has syntax highlighting.

3. Syntax Highlighting = Structural Clarity

Syntax highlighting is not cosmetic.

It gives:

  • Immediate cognitive separation
  • Visual parsing of logic
  • Faster code reviews
  • Better debugging
  • Clear boundaries between execution layers

In CS:

  • SQL blocks define queries
  • ETLX blocks define workflows
  • Markdown structures define dashboards
  • Code blocks remain readable and portable

The document becomes both:

  • Executable reference
  • Visual explanation

4. Markdown Dashboards

In CS, dashboards are Markdown-driven.

This means:

  • Layout is structured using headings
  • Data blocks embed SQL queries
  • Visual components are defined declaratively
  • Narrative explanation lives next to the query

Example:

  ### Revenue by Segment

```sql
SELECT segment, SUM(amount) AS revenue
FROM sales
GROUP BY segment
```

This approach:

  • Keeps analytics transparent
  • Avoids hidden visual builders
  • Makes dashboards auditable
  • Keeps business logic visible

The dashboard becomes documentation. The documentation becomes the dashboard.

5. ETLX Workflows in Markdown

ETLX workflows can also be defined using Markdown-structured metadata.

Instead of designing pipelines in drag-and-drop tools:

  • The pipeline is defined declaratively
  • The steps are readable
  • Transformations are explicit
  • Inputs and outputs are visible

Example:

  workflow:
  name: revenue_aggregation
  schedule: daily
  steps:
    - extract: postgres.sales
    - transform: aggregate_by_segment
    - load: duckdb.analytics

This makes workflows:

  • Transparent
  • Reviewable
  • Version-controlled
  • Reproducible

No hidden state. No visual black boxes.

6. Markdown is LLM-Friendly

This is where Markdown becomes strategic.

Large Language Models (LLMs):

  • Are trained primarily on text
  • Understand Markdown structure naturally
  • Parse headings and code blocks cleanly
  • Recognize language fences (sql, yaml, etc.)

This means:

  • LLMs can generate ETLX workflows
  • LLMs can generate dashboards
  • LLMs can refactor SQL inside Markdown
  • LLMs can reproduce full analytics documents
  • LLMs can reason about the structure of pipelines

Because everything is text.

No proprietary binary format. No hidden UI metadata. No drag-and-drop artifacts.

Just structured text.

7. AI-Assisted Reproducibility

Because CS uses Markdown:

An LLM can:

  • Read your dashboard
  • Understand your SQL
  • Suggest improvements
  • Generate new workflows
  • Refactor pipelines
  • Create new ETLX definitions
  • Translate business requirements into structured metadata

This makes CS:

  • AI-augmentable
  • AI-generatable
  • AI-reviewable
  • AI-extensible

Markdown becomes the shared language between:

Human ↔ Platform ↔ AI

8. Version Control & Governance

Markdown works perfectly with:

  • Git
  • Pull requests
  • Code reviews
  • CI/CD
  • Audit trails

You can:

  • Review a dashboard change like code
  • Diff a pipeline modification
  • Roll back transformations
  • Track evolution over time

Dashboards and workflows become:

Infrastructure-as-text.

9. Portability & Longevity

Markdown:

  • Is not tied to CS
  • Is not tied to a vendor
  • Is not tied to a database
  • Is not tied to a rendering engine

If CS disappeared tomorrow:

Your dashboards and workflows would still be readable.

Plain text outlives platforms.

10. Philosophy Alignment with Central Set

Central Set believes:

The database is the source of truth. Configuration defines behavior. Text defines structure.

Markdown fits this philosophy perfectly.

It is:

  • Transparent
  • Declarative
  • Structured
  • Extensible
  • AI-native

Why Not Visual Builders?

Visual tools:

  • Hide logic
  • Store metadata in opaque formats
  • Make version control painful
  • Break reproducibility
  • Resist AI interpretation

Markdown:

  • Makes logic explicit
  • Keeps structure visible
  • Encourages documentation
  • Enables automation
  • Aligns with modern AI workflows

Final Thought

Markdown is not just formatting.

It is:

  • A documentation system
  • A dashboard definition language
  • A workflow definition language
  • A version-controlled artifact
  • An AI-compatible interface

In Central Set:

Markdown is the connective tissue between:

Database Admin API Pipelines Analytics AI

If you believe systems should be:

Readable. Portable. Reproducible. AI-augmentable.

Then Markdown is not optional.

It is foundational.

Edit this page

Last updated 09 Mar 2026, 20:28 -01 . history

Was this page helpful?