Style Guide

Best practices and conventions for writing clean, readable .chalk documents.

Table of Contents

Document Headers

Place document headers at the start of your .chalk files, before any content or elements.

Good:

*(
    title: My Article
    author: Jane Doe
    date: 2025-12-19
)

# Introduction

Content starts here...

Avoid:

# Introduction

*(title: My Article; author: Jane Doe)

Content here...

Headers provide essential metadata about the document and should be immediately visible when opening a file.

Attribute Syntax

Single-Line Attributes

Use single-line attribute syntax when an element has:

Examples:

image(src: photo.jpg; alt: Sunset; caption: Beautiful)

link(url: https://example.com; text: Click here)

metadata(version: 1.0)

Multi-Line Attributes

Use multi-line attribute syntax for headers or when an element has:

With Body Section:

section{
    This is the section content.
}(
    title: Introduction
    collapsed: false
    id: intro-section
)

callout{
    Important information here.
}(
    type: warning
    title: Note
)

With Detail Section:

accordion{
    Summary content visible by default
}[
    Hidden detail content
](
    expanded: false
    theme: light
)

Many Attributes (No Body):

config(
    host: localhost
    port: 8080
    ssl: true
    debug: false
)

Element Structure

Standard-Syntax Element Order

Follow this order for element sections:

  1. Body {...} - Main content (if applicable)
  2. Detail [...] - Secondary content (if applicable)
  3. Attributes (...) - Configuration (if applicable)
element{
    body content
}[
    detail content
](
    attributes
)

Nested Elements

Indent nested elements consistently for readability:

article{
    section{
        # Introduction
        
        This is a paragraph.
    }(
        title: Getting Started
    )
    
    section{
        # Advanced Topics
        
        More content here.
    }(
        title: Advanced
    )
}(
    published: true
)

Formatting Conventions

Indentation

Use consistent indentation (2 or 4 spaces) for nested content:

parent{
    # Level 1
    
    child{
        # Level 2
        
        Content here
    }(
        attr: value
    )
}(
    theme: dark
)

Spacing

Between Elements:

Use blank lines to separate top-level elements:

section{
    First section
}(
    title: One
)

section{
    Second section
}(
    title: Two
)

Within Attributes:

No blank lines between attributes in multi-line syntax:

element(
    one: value1
    two: value2
    three: value3
)

Line Breaks

Break long attribute values naturally:

element(
    title: This is a very long title that describes the content
    description: Another long piece of text that provides details
    url: https://example.com/very/long/path/to/resource
)

Examples

Well-Styled Document

*(
    title: Product Documentation
    author: Engineering Team
    version: 2.0.0
    date: 2025-12-19
)

@const(product: MyApp; version: 2.0.0)

# Welcome to {{product}}

This documentation covers version {{version}}.

section{
    # Getting Started
    
    Follow these steps to begin:
    
    steps{
        Install the package
        Configure your environment
        Run the application
    }(
        numbered: true
    )
}(
    id: getting-started
    expanded: true
)

callout{
    Make sure to read the prerequisites before continuing.
}(
    type: info
    title: Prerequisites
)

section{
    # API Reference
    
    Detailed API documentation...
}(
    id: api-reference
)

Comparison

Poor Style:

section(title: Intro; id: intro-1; collapsed: false; theme: light){# Introduction
Content here}
image(src: photo.jpg;alt: Photo;caption: A beautiful sunset;width: 800;height: 600)
*(title: Doc;author: Me)

Good Style:

*(
    title: Doc
    author: Me
)

section{
    # Introduction
    
    Content here
}(
    title: Intro
    id: intro-1
    collapsed: false
    theme: light
)

image(
    src: photo.jpg
    alt: Photo
    caption: A beautiful sunset
    width: 800
    height: 600
)

Summary