FAQ
Frequently asked questions about .chalk and the dotchalk project.
Table of Contents
General Questions
What is .chalk?
.chalk is a modular, library-based markup language that enables developers to build document-based applications with domain-specific, user-friendly syntax. Unlike fixed-syntax languages, .chalk allows developers to define custom element types through libraries, making it adaptable to any use case—from documentation platforms and CMS systems to educational software, form builders, and content management tools.
Developers create libraries that define the structure, validation, and behaviour of documents, while end users (or the developers themselves) author content using simple, readable syntax tailored to the specific domain.
Why create a new markup language?
Existing markup languages like Markdown and HTML have limitations:
- Markdown is great for simple documents but lacks extensibility and structure for complex content
- HTML is powerful but verbose and not human-friendly
- MDX requires JavaScript knowledge and ties you to React
- AsciiDoc has a steep learning curve and rigid syntax
.chalk bridges these gaps by combining:
- Human-readable syntax (like Markdown)
- Full extensibility through libraries
- Strong typing and validation
- Domain-specific customisation
- Language-agnostic compilation to JSON
Who should use .chalk?
.chalk is ideal for:
- Application developers building document-based systems (CMS platforms, documentation tools, educational software, form builders)
- Teams creating content-heavy applications that need domain-specific markup languages
- Developers who want to provide users with simple, intuitive syntax for structured content
- Anyone building tools where users need to author structured documents with validation and type safety
Is .chalk production-ready?
The dotchalk JavaScript implementation is functional and tested, but the project is not yet formally released as open source. The core API is stabilising, but breaking changes may occur before v1.0. See the Roadmap for future plans.
Comparison with Other Markup Languages
.chalk vs Markdown
| Feature | .chalk | Markdown |
|---|---|---|
| Syntax | Non-technical, human-friendly | Simple, fixed syntax |
| Domain Specificity | Fully customisable for any domain | Generic, one-size-fits-all |
| Extensibility | Modular library system with custom elements | Limited (usually via HTML fallback) |
| Fine-Grained Control | Define element types, attributes, validation rules | No control over structure |
| Structure | Enforced via content policies | Minimal |
| Attributes | Rich, typed attribute system | Limited (HTML-style for images/links) |
| Validation | Built-in via library definitions | None |
| Output | Structured JSON | HTML (typically) |
| Learning Curve | Low to moderate | Very low |
| Use Case | Domain-specific structured content | General-purpose documentation |
When to use .chalk over Markdown:
- You’re building a document-based application that needs custom, domain-specific elements
- You want to provide users with simple syntax while maintaining full control over structure
- You need modular, reusable element definitions via libraries for your application
- You require fine-grained control over element structure and validation for your users
- You want structured data output (JSON) to power your application, not just HTML
- Your application needs domain-specific markup tailored to a specific use case
When to use Markdown over .chalk:
- You need universal tool support (editors, parsers, converters)
- You’re writing simple documents, not building an application
- You want the widest adoption and familiarity
.chalk vs MDX
| Feature | .chalk | MDX |
|---|---|---|
| Syntax | Non-technical, domain-specific elements | Markdown + JSX (technical) |
| Domain Specificity | Fully customisable libraries | Component-based |
| Extensibility | Modular library system (language-agnostic) | React component-based |
| Runtime | No JavaScript required | Requires React |
| Type Safety | Built-in via attribute types | TypeScript integration available |
| Learning Curve | Low to moderate | Moderate to steep (requires React knowledge) |
| Output | Structured JSON | React components |
| Portability | Works in any language | Tied to JavaScript/React ecosystem |
When to use .chalk over MDX:
- You’re building document-based applications outside the React ecosystem
- You want to provide users with non-technical, readable syntax for authoring
- You need modular libraries that work across different tech stacks and applications
- You prefer language-agnostic content that compiles to structured data
- You want separation between content structure and presentation in your application
- Your users shouldn’t need React/JavaScript knowledge to author content
When to use MDX over .chalk:
- You’re already using React
- You want to embed interactive components directly
- You need the React ecosystem and tooling
.chalk vs AsciiDoc
| Feature | .chalk | AsciiDoc |
|---|---|---|
| Syntax | Non-technical, intuitive | Technical, extensive syntax |
| Domain Specificity | Fully customisable for any domain | Fixed for technical documentation |
| Extensibility | Modular library system | Low (fixed syntax) |
| Fine-Grained Control | Define your own element types and rules | Use predefined elements only |
| Structure | Library-defined | Predefined |
| Validation | Built-in | Limited |
| Learning Curve | Low to moderate | Steep |
| Output | Structured JSON | DocBook XML, HTML, PDF |
| Use Case | Domain-specific applications | Technical documentation, books |
When to use .chalk over AsciiDoc:
- You’re building document-based applications that need domain-specific elements
- You want to provide users with non-technical, intuitive syntax for content authoring
- You need modular, customisable libraries tailored to your application’s specific domain
- You require fine-grained control over element definitions and validation for your users
- You’re building an application that consumes structured content as data (JSON)
- Your application needs markup beyond traditional technical documentation
When to use AsciiDoc over .chalk:
- You’re writing long-form technical documentation or books
- You need established publishing toolchains (PDF, ePub)
- You want comprehensive built-in features without customisation
.chalk vs reStructuredText
| Feature | .chalk | reStructuredText |
|---|---|---|
| Syntax | Non-technical, domain-specific | Technical, Python-influenced |
| Domain Specificity | Fully customisable for any domain | Fixed for documentation |
| Extensibility | Modular library system | Medium (directives) |
| Fine-Grained Control | Full control over element types | Limited to predefined directives |
| Ecosystem | Growing | Mature (Python/Sphinx) |
| Output | Structured JSON | HTML, LaTeX, various |
| Learning Curve | Low to moderate | Moderate to steep |
| Primary Use | Domain-specific applications | Python documentation |
When to use .chalk over reStructuredText:
- You’re building document-based applications with domain-specific needs
- You want to provide users with non-technical, readable syntax for content authoring
- You need modular libraries tailored to your application’s specific domain
- You require fine-grained control over structure and validation for your users
- You’re not in the Python ecosystem
- Your application consumes structured data (JSON) rather than generating static output
When to use reStructuredText over .chalk:
- You’re documenting Python projects
- You’re using Sphinx
- You need the mature RST tooling ecosystem
.chalk vs XML/HTML
| Feature | .chalk | XML/HTML |
|---|---|---|
| Readability | High (non-technical, human-friendly) | Low (verbose, technical) |
| Syntax | Minimal, intuitive | Tag-based, verbose |
| Domain Specificity | Built-in via library system | Requires custom namespaces/schemas |
| Extensibility | Modular library-based elements | Namespace-based (XML) |
| Fine-Grained Control | Element definitions with validation | Schema-based validation |
| Validation | Built-in via libraries | Requires external schemas (XSD, DTD) |
| Learning Curve | Low to moderate | Low (familiar) |
| Output | Structured JSON | Typically direct use |
| Primary Use | Human-authored, domain-specific content | Machine-generated, APIs |
When to use .chalk over XML/HTML:
- You’re building document-based applications where users author content
- You want to provide users with non-technical syntax that’s easily readable and maintainable
- You need domain-specific elements without XML namespace complexity
- You want modular libraries with built-in validation (no external schemas needed)
- Your application needs structured data authored by humans, not machines
- You require fine-grained control over element structure with user-friendly syntax
- You prefer minimal, intuitive syntax over verbose tags for your users
When to use XML/HTML over .chalk:
- You need universal format support
- Existing tooling and ecosystems are critical
- You’re working with machine-generated content
- You need namespace support
Technical Questions
Can I nest elements infinitely?
Nesting depth depends on your library’s content policies. Each element defines what child elements it allows via bodyPolicy and detailPolicy. You can create deeply nested structures if your policies permit it, but there are no hard limits imposed by Chalk itself.
How are constants typed?
Constants defined with @const() are initially stored as strings. During compilation, when a constant is referenced in an attribute, it’s parsed according to that attribute’s type. For example:
@const(count: 42; enabled: true)
element(limit: {{count}}; active: {{enabled}})
If limit is defined as type number and active as boolean, the constant values will be parsed accordingly. See Constants for details.
What’s the difference between body and detail sections?
- Body
{...}: Main content of an element - Detail
[...]: Optional secondary/sidebar content
This separation allows for flexible layouts. For example, an article element might use body for main text and detail for author bio or related links. Not all elements support detail sections—it depends on the library definition.
Can I use .chalk in the browser?
Yes! The dotchalk library works in Node.js and can be bundled for browser use with tools like Webpack, Rollup, or Vite. Since compilation produces JSON, you can compile on the server or client depending on your needs.
A future WebAssembly version is planned for better browser performance. See the Roadmap.
Library Development
How do I create my own library?
Start with the Library Reference documentation. Basic steps:
- Define your document structure with
createDocument() - Create element definitions with
createElement() - Add custom attribute types (using
.type()or.enum()for enumerations) if needed - Add elements to your library with
lib.add() - Use the library to compile documents
See Complete Examples for working code.
Can I share libraries?
Yes! Libraries are just JavaScript/TypeScript objects that can be published as npm packages or shared as modules. You can create reusable libraries for specific domains (e.g., a blog library, documentation library, form library) and distribute them.
How do content policies work?
Content policies control what elements can appear in an element’s body or detail sections:
'literal'- Plain text only (elements only)null- No content allowed (elements only)['element1', 'element2']- Only specified elements'all'- Any element allowed
Policies enable validation and ensure document structure consistency. See Content Policies for details.
Have more questions? Check the Troubleshooting Guide or review the Language Guide and API Reference.