URL Hierarchy

In MDXLD, everything is URL-based. This creates a fundamentally different model from traditional file systems.

Files vs URLs

Traditional File System:

/agents/           ← folder (no content)
/agents/sales-bot  ← file (has content)

A path is either a file OR a folder, never both.

URL System (MDXLD):

/agents            ← HAS content AND children
/agents/sales-bot  ← HAS content AND children
/agents/sales-bot/qualify  ← HAS content AND children

Every URL is both a resource (returns content) AND a namespace (has children).

Heading ↔ URL Duality

Markdown heading hierarchy maps directly to URL hierarchy:

# Sales Bot                    → /sales-bot
## Qualify                     → /sales-bot/qualify
### Score Lead                 → /sales-bot/qualify/score-lead
### Enrich Data                → /sales-bot/qualify/enrich-data
## Email                       → /sales-bot/email
## Book Meeting                → /sales-bot/book-meeting

This creates a powerful bidirectional conversion:

Single File View

# Sales Bot

Introduction to the sales bot agent.

## Qualify

The qualification process for leads.

### Score Lead

Calculate lead score based on criteria.

### Enrich Data

Enrich lead data from external sources.

## Email

Send personalized emails to leads.

## Book Meeting

Book meetings on the calendar.

URL Tree View

/sales-bot/                     (# content)
/sales-bot/qualify/             (## content)
/sales-bot/qualify/score-lead   (### content)
/sales-bot/qualify/enrich-data  (### content)
/sales-bot/email                (## content)
/sales-bot/book-meeting         (## content)

Explode & Collapse Operations

Explode

Convert a heading into a child URL (extract to its own document):

# Sales Bot

## Qualify        ← Right-click → "Explode to URL"

Content here...

Becomes:

/sales-bot           # Sales Bot (without ## Qualify section)
/sales-bot/qualify   # Qualify (content moved here)

Collapse

Inline a child URL as a heading (merge back into parent):

/sales-bot           ← Select "Collapse children"
/sales-bot/qualify   ← Gets inlined as ## Qualify

Becomes:

# Sales Bot

## Qualify

Content from /sales-bot/qualify inlined here...

Relative Heading Levels

The heading level is relative to the URL depth:

Viewing URL	Content at `/sales-bot/qualify` displays as
`/sales-bot`	`## Qualify` (child)
`/sales-bot/qualify`	`# Qualify` (root of this URL)
`/`	`### Qualify` (grandchild)

Formula:

headingLevel = childUrlDepth - parentUrlDepth + 1

Why This Matters

No Sandbox Needed

Because everything is URL-based:

Imports resolve to URLs (fetched from db or CDN)
No arbitrary file system access
Worker Loader loads code from URLs
Isolation is natural (each isolate only sees what it imports)

import { qualify } from './qualify'           // Relative URL
import { sendEmail } from 'https://functions.do/email'  // Absolute URL

Flexible Granularity

Start with everything in one document
As sections grow complex, explode them to their own URLs
Collapse simple children back into the parent
Same content, different organization

URL = Identity

Every piece of content has a stable URL ($id):

$id: https://agents.do/sales-bot/qualify

This URL is:

The content's identity
Its API endpoint
Its import path
Its link target

Data Model

interface UrlNode {
  $id: string                    // Full URL
  $type: string                  // Noun type
  content: string                // MDXLD content (this level only)
  children: UrlNode[]            // Sub-URLs

  // View modes
  collapsed(): string            // Single MDXLD with all children as headings
  exploded(): UrlNode[]          // Tree of separate MDXLD documents
}

Editor Integration

The URL Editor supports both views:

View	Description
Document	Single file with nested headings
Tree	Folder-like navigation of URLs
Split	Tree on left, document on right

Toggle between views seamlessly - the underlying data is the same.

URL Hierarchy

On this page