MarkCharm

Built for humans. Loved by AI. Working for all.

MarkCharm is a robust compiler that unites the pristine simplicity of Markdown with the deterministic typographic control of LaTeX. It is designed for generating technical and legal documents complying with strict formatting standards (e.g., ABNT NBR 6024).

[!WARNING] Early Access / Beta Status MarkCharm is currently in a closed Beta phase. Our primary focus right now is stabilizing the core HTML engine and the AST parser. Expect bugs, breaking changes in experimental features, and missing output formats. Your feedback is vital!

🚦 What works and what doesn't?

🟢 Rock Solid (Ready for Testing):

• Native hierarchical paragraph numbering & ABNT compliance.
• Cross-references with auto-pluralization (§§) and NLG.
• Production-ready HTML generation.

🟡 Experimental (Expect turbulence):

• Data-binding ({#DATA}) from external sources.
• Sandboxed script execution ({#EXEC}) and Excel spreadsheet integration.
• Custom LaTeX-style Macros.

🔴 Not Available Yet:

• Exporting to Markdown, LaTeX, JSON AST, or PDF natively.
• Open access to the GitHub repository source code.

🚀 What's New in 0.87.1-beta

MarkCharm 2.0 introduces a paradigm shift in how structured documents are compiled, featuring our new decoupled 5-module StylePack Engine:

• Style-Agnostic Core: The core parser and backends are now 100% blind to specific styles. All logic (numbering, margins, CSS) is completely offloaded to external .yaml StylePacks and .mc preambles!
• Data Binding ({#DATA}): Seamlessly bind external data sources directly into the document AST, generating dynamic tables without writing a single line of script.
• AI-First Authoring (markcharm init-ai): Native capabilities built specifically for LLM code-assistants. Includes AI-visible comments ({@ prompt }) and token-efficient compiler diagnostics via --error-format llm.
• New Built-in StylePacks: Native support for \style{pindorama} (Brazilian Government SoRs), \style{abnt_legal}, and \style{technical} out of the box.

🌟 Why MarkCharm? (Key Features)

1. 📐 Compliance & Automatic Numbering

• Native Standards Support: Simply add \style{brazilian} or \style{pindorama}. The compiler will automatically enforce correct numbering logic for all chapters, sections, and floating elements (Figures, Tables, Quadros).
• Paragraph Numbering (\paragraph_numbering): Essential for legal drafting. Automatically numbers paragraphs hierarchically (e.g., 1.1, 1.1.1) based on their parent section. It handles legal ordinal rendering for first paragraphs (e.g., § 1º).

2. 🔗 Intelligent Cross-References (NLG)

Say goodbye to broken links and manual singular/plural tracking.

• Auto-Pluralization: Referencing multiple anchors (e.g., \cref{fig1, fig2}) automatically generates localized natural language lists: "figuras 1 e 2".
• Natural Language Generation (\nlg{on|off}): Dynamically inflects prepositions and gender agreements based on the target element.
• Context-Aware Pruning: Reduces reference noise. If referencing Figure 3.1 from within Section 3, it can smartly emit just "Figure 1" if unambiguous.

3. 🛠️ LaTeX-style Macros & Spreadsheets

• Custom Macros (\newcommand): Define reusable text expansion patterns with positional arguments (#{1}) and named parameters.
• Spreadsheet Integrations (\spreadsheet): Native capability to render regions of .xlsx or .ods files dynamically inside your document by A1 coordinates (region="A1:E4") or Named Range Aliases.
• Bibliography & Citations (\bibliography): Parse .bib databases, generate inline citations, and produce localized reference sections.

4. ⚡ Dynamic Sandboxed Scripting ({#EXEC})

Embed Python, Bash, or Node scripts directly inside your document fenced blocks using {#EXEC}. MarkCharm will execute them safely and inject their output back into the AST. Execution is strictly bounded by CPU timeouts and memory output limits to ensure security (or entirely blocked via --safe).

🎯 Positioning & Strategic Niches

Landscape: Markdown vs. Typst vs. LaTeX vs. MarkCharm

Four Core Strategic Niches

1. 🏛️ Public Sector & Government Procurement (GovTech / B2G):

   • Automated authoring of complex Statements of Requirements (SoR) (Termos de Referência under Brazilian Bidding Law 14.133/2021), bidding notices, and regulatory reports.
   • Dynamic hierarchical paragraph numbering and atomic clause cross-references (\dlref, \llref, \sref) that never break when clauses are reordered.
   • Built-in compliance with federal standards (SISP, IMR tables, and IBGE open-sided statistical tables).

2. ⚖️ Corporate Legal & Compliance (LegalTech):

   • High-stakes contracts (M&A, shareholder agreements, compliance audits, ISO 27001).
   • Strict compile-time validation: referenced clauses that are moved or removed trigger compiler errors (MCE-REF-*), preventing multimillion-dollar legal disputes caused by broken contract cross-references.
   • Cryptographically auditable document baselines (deterministic AST hashing).

3. 📊 Living Technical Documentation & Engineering:

   • Engineering manuals, inspection logs, and executive reports driven by live data.
   • Reactive data binding ({$DATA data.xlsx region=B2:G15}) and automatic natural-language numbers (\numext{}) ensuring that when source spreadsheets update, documents rebuild without manual copy-paste errors.

4. 🤖 AI-Agent Autonomous Document Engineering:

   • Built from the ground up for collaborative human-AI document creation.
   • The LLM compiler loop: agents generate .mc and validate with markcharm check-dir . --error-format llm. Errors provide precise, token-efficient diagnostics, enabling autonomous self-healing.
   • Privacy namespaces: {@ ... @} comments guide AI authoring tools, while confidential secrets inside {@! ... @!} are strictly purged before inference.

5. 🛡️ Document-as-Code & CI/CD Pipelines:

   • Treats official documents as software artifacts that can break builds if structural rules aren't met.
   • Native enterprise ontology traceability (markcharm trace) against SSOT JSONs and topology.yaml hierarchical rules (e.g., mitigating Risks, mapping Features to Architecture Components).
   • Validation against ghost requirements, orphan relationships, and structural regressions.
   • Structural schema validation (markcharm validate --schema) and CI/CD data mocking (--mock-data).
   • Blocks invalid layouts via preamble directives ({#ASSERT expr="section_count > 2"}).

Read the full technical whitepaper in docs/architecture/POSITIONING_AND_COMPETITIVE_ANALYSIS.md.

🚀 Quick Start

MarkCharm requires Python 3.10+.

Installation

We strongly recommend installing MarkCharm globally using pipx (to avoid Python environment conflicts) or in an isolated virtual environment using pip.

# Recommended: Install globally using pipx
pipx install markcharm

# Note: If this is your first time using pipx, you might need to run:
# pipx ensurepath
# and restart your terminal. If pipx warns about existing symlinks, run:
# pipx install markcharm --force

# Or using pip in a virtual environment
pip install markcharm

Note: The official GitHub repository is currently private during the Beta phase. Installation is strictly via PyPI packages.

For developers and contributors, you can also install extra dependencies for native MathML generation (pipx install markcharm[math]) or Jupyter rich outputs (pipx install markcharm[jupyter]).

Your First Document

1. Create a document.mc file:

   \language{en}
   \style{technical}
   \author{Jane Doe}
   \date{\today}
   
   \maketitle
   
   # Introduction [intro]
   Welcome to MarkCharm! As we will see in \Cref{data}.
   
   ## Telemetry [data]
   Data flows seamlessly.
   

2. Compile via CLI:

   # Compile to HTML
   markcharm document.mc -f html -o output.html
   
   # Or use Live Reloading while writing
   markcharm watch document.mc
   

3. Configure your AI Assistant:

   # Generate prompt guidelines and workspace rules for Cursor, GitHub Copilot, or Gemini
   markcharm init-ai .
   

📚 Ecosystem & Documentation

MarkCharm ships with comprehensive documentation included in the package:

• USER_GUIDE.md: The comprehensive manual for writers. Details all commands, mathematical syntax, scripting configurations, and macro writing.
• SPEC.md: The normative language specification. It documents grammatical structures, error codes (MCE/MCW), and the rigorous rules engine expected by the parser.
• DEVELOPER_GUIDE.md: The technical blueprint outlining the 5-module compilation pipeline, AST nodes, and how to write new language plugins.
• man pages: Standard Linux man page available via man markcharm.

Access all bundled documentation at any time by running:

markcharm docs

🎨 Official Demos

MarkCharm ships with 70+ built-in demo documents showcasing every major feature. You can explore them directly from your installation:

markcharm docs

Popular showcases include:

• Cross References: Advanced NLG and auto-pluralization examples.
• Spreadsheets: Dynamic Excel / ODS rendering inside documents.
• Script Automation: Python AST mutation using {#EXEC} sandboxed blocks.
• Custom Styles: Creating complex custom styles entirely in .mc preambles without writing Python.

🤝 Contributing

MarkCharm is an evolving ecosystem. Currently in v0.87.1-beta, we are rapidly approaching the stable 1.0.0 core. If you are a parser enthusiast, a LaTeX veteran, or just love structured documents, we welcome contributions!

Note: The source code repository is currently private during the Beta phase. If you are interested in contributing, please reach out via the PyPI project page. Source access will be opened progressively as we approach the 1.0.0 stable release.

📄 License & Versioning

• Core Compiler License: The MarkCharm software engine is an open-source project released under the Apache License 2.0. You are free to use, modify, and distribute the compiler in both academic and commercial applications without restriction.
• Language Specification License: The MarkCharm Official Language Grammatical Standard (SPEC.md) is strictly protected under the Creative Commons Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0). You may copy and redistribute the document freely, but you may not distribute modified or derived dialects of the specification text.

AI Assistance Disclaimer

This software was developed with the assistance of Artificial Intelligence tools (OpenAI ChatGPT, Anthropic Claude, and Google Gemini) across all phases of development, including architecture design, code generation, testing, and documentation.