This directory contains the official specification documents for the 3md (Trilingual Markdown) format.
The complete 3md format specification defining:
- Language declaration syntax
- The two separator types (inline
~and block෴) - Markdown integration
- Metadata and frontmatter
- Complete syntax reference
This is the canonical reference for implementing 3md parsers and tools.
Error handling specification defining:
- Validation rules
- Error codes and messages
- Parser behavior for invalid input
- Recovery strategies
Follow this spec when implementing error reporting in 3md tools.
Implementation guidelines for tool builders:
- Recommended parsing strategies
- Edge cases and considerations
- Best practices for converter tools
- Testing recommendations
The examples/ directory contains canonical 3md documents that demonstrate the format and serve as test cases:
- simple-inline.3md - Basic inline separators (~)
- block-separator.3md - Block separators (෴) with multi-line content
- mixed.3md - Mixed inline and block separators
- colombo.3md - Comprehensive real-world example about Colombo city
- minimal.3md - Minimal valid 3md document
Each example includes the original .3md file and the expected output as separate language files (.si.md, .ta.md, .en.md).
All 3md implementations should correctly parse these examples.
Current Version: 0.1.0 Status: Draft Last Updated: 2025-12-29
The specification is under active development. Breaking changes may occur before version 1.0.0.
A conforming 3md implementation must:
- Correctly parse the language declaration
{{langs|si|ta|en}} - Handle inline separators (~) in headings, paragraphs, and list items
- Handle block separators (෴) for multi-line content
- Preserve markdown formatting in extracted language content
- Follow error handling rules defined in ERRORS.md
- Pass all canonical examples in the examples/ directory
To propose changes to the specification:
- Open an issue describing the problem or use case
- Discuss the proposed change with maintainers
- Submit a pull request with specification updates
- Update canonical examples if syntax changes
The 3md specification is released under CC BY 4.0.
You are free to:
- Implement the specification in any software
- Use 3md files for any purpose
- Build tools and services around 3md
- Modify and adapt the specification with attribution
- Root README - Overview of 3md and use cases
- Parser Implementation - Reference TypeScript parser
- Documentation - Additional guides and articles