Skip to content

todo.md

Latest commit

 

History

History
462 lines (331 loc) · 13.5 KB

todo.md

File metadata and controls

462 lines (331 loc) · 13.5 KB
Raw

Zolt v0.1 - Implementation Todo List

1. Core Parser & Lexer

Phase 0: Escaping & Comments

  • Implement escape character handling (\) (tested in escaping.e2e.spec.ts)
  • Implement :::comment blocks
  • Implement inline comments %% ... %%

Phase 0.5: File metadata

  • Parse YAML file metadata at start of file
  • Create automatic variables from file metadata ({$title}, {$author}, {$date}, {$version}, {$tags}, {$description}, {$lang}, {$toc}, {$theme})
  • Implement theme system (default, professional, technical, playful)
  • Support colorScheme (auto, light, dark) with automatic system preference detection
  • Generate HTML <meta> and Open Graph tags from file metadata (with strict TS typing)

Phase 1: Variables

  • Parse variable definitions $var = "value"
  • Replace variable occurrences {$var} (Note: skipped inside code spans and code blocks)
  • Implement automatic date variables ({$created}, {$modified})
  • Support date formatting with Date.format() function (tokens: DD, MM, YYYY, YY, HH, H, hh, h, mm, ss, a, MMMM, MMM, dddd, ddd, m, s)
  • Support date localization using $lang or $locale variables in Date.format()
  • Implement AST-based evaluation for :::foreach, :::if, and expressions (replaces SourceEvaluator)

2. Universal Attribute System {}

Attributes on All Elements

  • Support {#id} and other attributes on ALL elements
  • Attributes on Paragraphs
  • Attributes on Lists and List Items
  • Attributes on Blockquotes
  • Attributes on All Inline Elements (Bold, Italic, etc.)
  • ||text||{attributes} - Apply styles to groups of words (Styled Inline Groups)

Attributes on Text Inline

  • {color=value} - Text color
  • {size=value} - Font size
  • {#id} - Unique identifier
  • {.class} - CSS classes
  • {background=value} - Background color
  • {fontWeight=value} - Font weight

Attributes on Headings

  • {#id} - Heading ID for cross-references
  • {.class} - CSS classes
  • {numbered} - Enable numbered
  • {numbered=false} - Disable numbered

Attributes on Images

  • {w=width} or {width=value} - Width (tested in images.e2e.spec.ts)
  • {h=height} or {height=value} - Height (tested in images.e2e.spec.ts)
  • {align=value} - Alignment (left, center, right)
  • {shadow=value} - Shadow (tested in images.e2e.spec.ts)
  • {float=value} - Float

Image Syntax

  • ![alt](src) - Basic image
  • ![alt](src){width=value} - Image with attributes

Attributes on Videos

  • {autoplay} - Autoplay (tested in images.e2e.spec.ts)
  • {loop} - Loop (tested in images.e2e.spec.ts)
  • {muted} - Son désactivé (tested in images.e2e.spec.ts)

3. Typography & Inline Formatting

Basic Formatting

  • **text** → Bold
  • //text// → Italic
  • __text__ → Underline
  • ~~text~~ → Strikethrough
  • ^{text} → Superscript (with nesting support)
  • _{text} → Subscript (with nesting support)
  • ==text== → Highlight/Mark

Styled Inline Groups

  • ||text||{attributes} - Apply styles to groups of words

Character Escaping

  • Escape special characters with backslash (tested in escaping.e2e.spec.ts)
  • Support double backslash for literal backslash (tested in escaping.e2e.spec.ts)

4. Lists

List Types

  • Bullet lists - item
  • Numbered lists 1. item
  • Task lists - [ ] task and - [x] task
  • Definition lists : term / : definition
  • Plain lists + item (without bullets)

List Features

  • Nested lists (2 spaces or 1 tab indentation)
  • Attributes on list items
  • Mixed list types

5. Links

Link Types

  • External links [text](url)
  • Links with attributes [text](url){attributes}
  • Automatic reference links [text][ref] with [ref]: url
  • Internal links/cross-references [text](@id)
  • Anchor links [text](#anchor)
  • Highlight target element on anchor navigation
  • Links with variables [text]({$var})
  • Link reference definitions [ref]: url

Link Attributes

  • {target=_blank} - Open in new tab (tested in images.e2e.spec.ts)
  • {rel=noopener} - Security for target=_blank (tested in links-security.e2e.spec.ts)
  • {title=value} - Tooltip (tested in links-security.e2e.spec.ts)

6. Blockquotes & Citations

Blockquote Features

  • Simple blockquotes > text
  • Blockquotes with attributes (on paragraph lines)
  • Nested blockquotes >> and >>>

7. Technical Indentation

Indentation System

  • Simple indentation & text
  • Multiple indentation levels &&, &&&
  • Distinction from blockquotes (>)
  • Nested indentation levels (returning to previous level)
  • Lists inside indentation blocks

8. Horizontal Rules

Rule Types

  • --- - Standard separator
  • *** - Thick separator
  • ___ - Thin separator
  • Separator with attributes {color}, {style}, {width}, {align}

9. Structure Blocks

Triple Colon Blocks :::

  • Semantic containers: :::info, :::warning, :::error, :::success, :::note
  • Optional titles :::type [Title]
  • Block attributes {attributes}
  • Details/accordion :::details [Title]
  • Details attribute {open=true}

Grid Tables

  • Basic tables with | syntax
  • [[table]] and [[/table]] wrapper
  • Header marker [h]
  • Column merge [colspan=N]
  • Row merge [rowspan=N]
  • Alignment markers :---, :---:, ---:
  • Table attributes {id=value}

Tabs

  • :::tabs container
  • :::tab [Title] items
  • Tabs container attribute {default=Name}
  • Tab item attribute {active=true}

Columns

  • :::columns container
  • :::column items
  • Container attribute {cols=N}
  • Column attributes {width=%}, {width=px}

10. Media Management

Media Prefixes

  • ![alt](url) - Images (jpg, png, gif, svg) → <img>
  • !![alt](url) - Videos (mp4, webm, ogg) → <video>
  • ??[alt](url) - Audio (mp3, wav, ogg) → <audio>
  • @@[alt](url) - Embeds (YouTube, Vimeo, Spotify) → <iframe>
  • &&[alt](url) - Downloadable files (pdf, doc, zip) → <a> with icon

11. Calculations & Logic

Basic Operators

  • Addition {{ a + b }}
  • Subtraction {{ a - b }}
  • Multiplication {{ a * b }}
  • Division {{ a / b }}
  • Modulo {{ a % b }}
  • Power {{ a ^ b }}
  • Ternary operator {{ condition ? trueVal : falseVal }}
  • Operator precedence (parentheses, power, mult/div/mod, add/sub)

Math Namespace

  • Math.floor(value)
  • Math.ceil(value)
  • Math.round(value)
  • Math.abs(value)
  • Math.pow(base, exp)
  • Math.sqrt(value)
  • Math.min(a, b, ...)
  • Math.max(a, b, ...)

List Namespace

  • List.length(array)
  • List.first(array)
  • List.last(array)
  • List.sum(array)
  • List.avg(array)
  • List.count(array) (alias of length)
  • List.min(array)
  • List.max(array)

String Namespace

  • String.upper(text)
  • String.lower(text)
  • String.length(text)
  • String.trim(text)
  • String.replace(text, search, replacement)
  • String.split(text, separator)
  • String.join(array, separator)

Date Namespace

  • Date.format(date, format) - Format a date with tokens (DD, MM, YYYY, YY, HH, H, hh, h, mm, ss, a, MMMM, MMM, dddd, ddd, m, s) and localization support.
  • Date.now() - Get current timestamp
  • Date.parse(text, format) - Parse a date string
  • Date.calc(date, duration) - Calculate a new date using a duration object
  • Date.diff(date1, date2) - Calculate difference between dates

Variables

  • Variable definitions $var = value
  • Multiline array/object definitions
  • Variable references {$var}
  • Property access {$obj.property}
  • Array access {$arr[index]}

Conditionals

  • Comparison operators ==, !=, <, <=, >, >=
  • Logical operators and, or
  • Conditional blocks :::if {{ condition }}

12. Document Logic

Footnotes

  • Footnote references [^n]
  • Footnote definitions [^n]: content
  • Multiple references to same footnote
  • Footnotes with attributes

Abbreviations

  • Inline abbreviations Text{abbr="definition"}
  • Global abbreviation definitions *[ABBR]: Definition
  • Abbreviations with additional attributes

Table of Contents

  • Basic TOC [[toc]]
  • TOC with attributes {depth=N}, {from=N}, {to=N}, {numbered=true}, {class=value}
  • Double bracket blocks with attributes [[toc {id=toc}]]

Loops

  • :::foreach {$array as $item}
  • Loop variables: {$foreach.index}, {$foreach.index1}, {$foreach.first}, {$foreach.last}, {$foreach.even}, {$foreach.odd}
  • Nested loops
  • Conditional rendering in loops with :::if

File Inclusion

  • {{include path/to/file.zlt}}
  • Relative path support
  • Recursion protection (max depth 10)
  • Loop detection
  • Variable inheritance from parent

13. Code Blocks & Special Functions

Advanced Code Blocks

  • Basic code blocks with triple backticks
  • Language-specific code blocks - PARTIAL (parsed but not highlighted)
  • Code block attributes: {title=value}, {highlight=N-M}, {start=N}
  • Syntaxic coloring
  • Add a button to copy code

Mathematics (LaTeX)

  • Inline math $ formula $
  • Block math $$ formula $$

Diagrams

  • :::mermaid blocks

Charts

  • :::chart container
  • :::chart-line - Line charts
  • :::chart-bar - Bar charts
  • :::chart-pie - Pie charts
  • :::chart-area - Area charts
  • Chart container attributes: {width}, {height}, {layout}
  • Chart attributes: {title}, {colorScheme}, {legend}, {grid}
  • Multi-chart support with horizontal/vertical layout

14. Heading Numbering

Global Numbering

  • $numbered = true - Enable global numbered
  • $numbered = "style" - Set numbered style

Local Numbering

  • {numbered} attribute on headings
  • {numbered=false} to disable specific sections

Numbering Styles

  • decimal - 1, 1.1, 1.1.1
  • roman-lower - i, ii, iii
  • roman-upper - I, II, III
  • alpha-lower - a, b, c
  • alpha-upper - A, B, C

15. Post-Processing

Automatic Features

  • Generate automatic heading IDs for headings without explicit {#id}
  • Process :::foreach loops with automatic variables (AST-based)
  • Generate Table of Contents at [[toc]] locations
  • Resolve cross-references @ref (tested in attributes.e2e.spec.ts)
  • Generate footnotes

16. Error Handling

Error Resilience

  • Continue parsing on syntax errors (handled by Parser catch-and-recover)
  • Emit warnings for unknown metadata in file metadata
  • Emit warnings for syntax errors (unclosed blocks, invalid attributes)
  • Validate attribute syntax (added validation in InlineParser.parseAttributes)
  • File not found errors for includes
  • Inclusion loop detection errors
  • Max depth exceeded errors
  • Permission denied errors

17. HTML Generation

Output

  • Generate valid HTML5
  • Apply CSS classes from attributes
  • Apply inline styles from attributes
  • Generate semantic HTML for blocks

18. Testing & Validation

Test Coverage

  • Unit tests for each inline formatting feature
  • Unit tests for each block type
  • Unit tests for attributes
  • Unit tests for variables
  • Unit tests for SourceEvaluator (:::foreach, :::if, :::comment blocks)
  • Unit tests for calculations and namespaces
  • Unit tests for loops
  • Unit tests for file inclusion
  • Integration tests for complete documents (charts, mermaid)
  • Regression tests for Markdown compatibility

19. Documentation

Developer Documentation

  • Update README with usage instructions
  • Document parser phases (done in ARCHITECTURE.md)
  • Document attribute system (done in spec.md and README.md)
  • Document all syntax features (done in spec.md)
  • Create migration guide from Markdown (done in README.md)

Documentation creator

  • Rename frontmatter to file metadata
  • Project metadata file
  • new layout metadata to set layout of current file (in file metadata) or globally (in project metadata file)
  • new sidebar markup to define sidebar structure
  • new filetree markup to display file tree based on the dependencies of the input file

20. Performance & Optimization

Performance

  • Optimize parsing speed
  • Minimize memory usage
  • Cache parsed results
  • Lazy loading for large documents

21. Maintenance & Infrastructure

  • Split E2E tests into themed files (*.e2e.spec.ts)
  • Update AGENTS.md with new test patterns
  • Clean up unused interfaces in CLI (BuildOptions, LintOptions)

22. CLI Features

  • Implement --watch option for automatic rebuilding
  • Recursive dependency tracking (links and includes) for watch mode
  • Automatic output directory creation

23. CLI Improvements

  • Add color to logs for lint and build commands

Legend

  • [ ] - Todo (not implemented)
  • [x] - Completed
  • [*] - In progress

Notes

  • Each checkbox represents a distinct feature to implement
  • Some checkboxes contain multiple sub-features
  • Features are organized by logical categories
  • Reference spec.md for detailed syntax and behavior requirements
  • Last updated: 2026-02-21