marXDown

Introduction

marXDown is a plugin for httbd and btty which lets humans and machines collaborate through a familiar, plain-text formatting language while producing fully conformant BettyDocs. It extends Markdown into the semantic age, allowing writers, developers, and machines to layer prose into semantic meaning. Each marXDown file is transformed into a BettyDoc, preserving context, metadata, and intent—bridging the readability and simplicity of Markdown with the structured, semantic, and federated data model of the BeTTY stack.

How It Works

marXDown converts Markdown into BettyDocs through either btty (the BeTTY command-line interface) or httbd (the network gateway). During conversion, templates defined in bettyd's JSON-LD override system enrich the document with linked data.

Headings become semantic anchors, lists translate into relationships, and metadata flows naturally from text. marXDown bridges human authorship and machine reasoning without requiring anyone to write a single line of JSON, converting your Markdown into a BettyDoc with embedded context and linked data references.

How marXDown Translates Files

When a Markdown file is submitted via btty or httbd, marXDown performs a multi-stage transformation pipeline:

1. Parse Markdown:
   The input document is parsed into an internal object representation (i.e., abstract syntax tree or AST).
2. Apply Template:
   marXDown identifies the appropriate template (as specified in the node's local configuration and/or overrides) and applies it to the parsed object.
3. Semantic Analysis:
   It analyzes the document's content, metadata, and structure (similar to how bettyd analyzes tags) to infer indexing requirements and populate the meta and fileType keys.
4. Conformant BettyDoc Output:
   The resulting output is a complete, conformant BettyDoc, ready for federation, indexing, and archival within a BeTTY node.

Template System and Schema Inference

marXDown's templates are themselves BettyDocs, stored and managed with btty and stored in bettyd's system lake. Each defines a schema for a particular subtype of BettyDoc, for example:

• Required keys and data types
• Expected metadata fields and tags
• Optional derived values or inferred indexes
• The mapping between Markdown structures (headers, lists, links) and JSON-LD fields

Why It Matters

marXDown democratizes the semantic web. It restores agency to authors by letting them create structured, machine-readable documents in a simple, popular interface, familiar to users of apps like Evernote and Reddit.

For BeTTY, marXDown is the language of collaboration where knowledge workers, journalists, researchers, and agentic AI can all write in the same breath.

marXDown makes BeTTY human-readable and writable. By giving users and developers a simple way to write structured data in plain text, it turns every Markdown file into a potential federated node of meaning. Your notes are now as searchable, shareable, and verifiable as all the other information on your node.

Writers and researchers gain semantic power without leaving their favorite editors. Developers can design plugins and workflows around an intuitive, text-based standard. Federated networks gain a bridge to existing content ecosystems (blogs, wikis, repos).

Integration

marXDown sits between memeograph and httbd in the BeTTY stack, serving as the authoring gateway for both human and machine agents. It transforms personal notes, social posts, and research logs into semantic assets ready to be published, federated, and analyzed.

Unlike bettyd, which only handles verified and conformant BettyDocs, marXDown operates at the interface layer, extending httbd and btty with the ability to:

• Parse and convert Markdown documents into structured BettyDocs.
• Define reusable BettyDoc templates using JSON-LD schemas.
• Apply those templates automatically to human-authored Markdown content.
• Generate federated, indexable, and semantically tagged data that integrates directly into BeTTY nodes.
• With marXDown installed, users can write in Markdown while taking advantage of BeTTY's federated indexing, encryption, and versioning, all without ever touching raw JSON.