Limitations and Roadmap

Limitations and Roadmap

This page documents known limitations of Apex and the planned roadmap for future development.

Known Limitations

Current Limitations

Strict XHTML in fragment (non-standalone) mode

Status: By design (documented)

Details:

• With --strict-xhtml but without --standalone, Apex applies XML-style serialization for void/empty HTML elements (same family of changes as --xhtml).
• It does not validate the full output as well-formed XML, and it does not repair arbitrary raw HTML. Content that is already ill-formed (unbalanced tags, unescaped & / < / > in text when raw HTML is allowed, etc.) may still produce output that is not valid XML.
• Full polyglot document headers (XML declaration, XHTML namespace, Content-Type meta) require --standalone.

Workaround: Use --standalone when you need a complete polyglot document wrapper, and avoid embedding problematic raw HTML if you require strict XML from a fragment.

1. Definition Lists Parsing

Status: Foundation complete, parsing needs enhancement

Details:

• Extension structure and HTML rendering are implemented
• Parsing logic to detect : lines and convert to definition lists needs completion
• Block-level content in definitions needs proper parsing

Workaround: Use standard lists or HTML for now.

Priority: Medium

2. Span-Level Inline Attribute Lists (IAL)

Status: Not implemented

Details:

• Block-level IAL ({: #id .class}) is fully supported
• Span-level IAL (*text*{:.class}) is not yet implemented

Workaround: Use block-level IAL or HTML attributes.

Priority: Low

3. HTML Markdown Attributes

Status: Not implemented

Details:

• Parsing markdown inside HTML tags based on markdown="1" attribute is not supported
• This is a complex feature requiring HTML parsing integration

Workaround: Use raw HTML or process HTML separately.

Priority: Low

4. MultiMarkdown Transclusion Syntax

Status: Partial

Details:

• Marked's include syntax (<<[file], <<(code), <<{html}) is fully supported
• MultiMarkdown's {{file}} syntax is not yet implemented
• Wildcard extensions ({{file.*}}) are not supported
• transclude base metadata is not supported

Workaround: Use Marked's include syntax in unified mode.

Priority: Low

5. Critic Markup Edge Cases

Status: Minor edge cases exist

Details:

• Most critic markup works correctly
• Some edge cases with nested markup or complex substitutions may have issues
• Generally works well for typical use cases

Priority: Low

6. Complete GitHub Emoji Set

Status: Partial (350+ emoji supported)

Details:

• 350+ common emoji are supported
• Full GitHub emoji set (1,800+ emoji) is not yet implemented

Workaround: Most common emoji work. Unsupported emoji will appear as text.

Priority: Very Low

Resolved Limitations

The following limitations have been resolved:

• ✅ Kramdown IAL - Full block-level implementation with ALD support
• ✅ Advanced Footnotes - Block-level content in footnotes now supported
• ✅ Advanced Tables - Colspan, rowspan, and captions fully implemented
• ✅ Callouts - All Bear/Obsidian/Xcode styles supported
• ✅ File Includes - Marked syntax fully implemented
• ✅ TOC Generation - All marker formats working
• ✅ Abbreviations - Full support implemented
• ✅ Page Breaks - Both HTML comment and Kramdown styles supported

Roadmap

Completed Features ✅

• Core Markdown parsing (CommonMark + GFM)
• Metadata blocks (YAML, MMD, Pandoc)
• Metadata variables ([%key])
• Wiki links ([[Page]])
• Math support ($inline$ and $$display$$)
• Critic Markup (all 5 types)
• GFM tables with alignment
• Strikethrough (~~text~~)
• Task lists (- [ ] and - [x])
• Autolinks
• Smart typography
• Footnotes (reference and inline styles)
• Abbreviations
• Callouts (Bear/Obsidian/Xcode)
• File includes (<<[file], <<(code), <<{html})
• TOC generation (all marker formats)
• GitHub Emoji (350+ common emoji)
• Page breaks (<!--BREAK-->, {::pagebreak /})
• Autoscroll pauses (<!--PAUSE:X-->)
• End of block markers (^)
• Kramdown IAL (block-level with ALD)
• Advanced footnotes (block-level content)
• Advanced tables (colspan, rowspan, captions)
• Header ID generation (GFM, MMD, Kramdown formats)
• Relaxed tables (no separator rows)
• Grid tables (Pandoc +---+ syntax, opt-in via --grid-tables)
• Definition lists foundation (HTML rendering)

High Priority (Next Release)

• Complete definition lists parsing
  • Detect : lines and convert to definition lists
  • Parse block-level content in definitions
  • Estimated: 1-2 hours

Medium Priority (Future Releases)

• MultiMarkdown transclusion syntax ({{file}})

  • Add {{file}} syntax for MMD mode compatibility
  • Support wildcard extensions ({{file.*}})
  • Support transclude base metadata
  • Estimated: 1-2 hours

• Span-level Inline Attribute Lists

  • Support *text*{:.class} syntax
  • Attach attributes to inline elements
  • Estimated: 2-3 hours

• Expand GitHub Emoji to full set

  • Add remaining 1,400+ emoji to reach 1,800+ total
  • Estimated: 2-3 hours (mostly data entry)

Low Priority (Nice to Have)

• HTML Markdown Attributes

  • Parse markdown inside HTML based on markdown="1" attribute
  • Handle block vs. span contexts
  • Estimated: 3-4 hours
  • Complexity: High

• Pygments syntax highlighting integration

  • Server-side syntax highlighting using Pygments
  • Cache results for performance
  • Estimated: 4-6 hours
  • Note: Client-side (Prism.js, highlight.js) is recommended instead

Future Considerations

• Performance optimizations

  • Profile and optimize hot paths
  • Memory usage improvements
  • Large document handling

• Additional Markdown extensions

  • Leanpub syntax support
  • Other processor-specific features based on user demand

• Enhanced error reporting

  • Better error messages
  • Syntax error highlighting
  • Validation warnings

• Plugin/extension system

  • Allow custom extensions
  • Third-party extension support

Version History

v0.1.0 (Current)

Status: Production-ready

Features:

• All core Markdown features
• GFM compatibility
• MultiMarkdown compatibility (partial)
• Kramdown compatibility (partial)
• Unified mode with all features
• Header ID generation
• Relaxed tables
• Comprehensive CLI tool
• C API and Objective-C wrapper

Known Limitations:

• Definition lists parsing incomplete
• Span-level IAL not implemented
• MMD transclusion syntax not implemented
• Grid tables: opt-in only (--grid-tables); some complex Pandoc grid layouts differ (column widths, general rowspan outside partial-separator tables)

Future Versions

v0.2.0 (Planned)

• Complete definition lists
• MMD transclusion syntax
• Additional emoji support

v0.3.0 (Future)

• Span-level IAL
• HTML markdown attributes
• Performance improvements

Contributing

If you'd like to help implement any of these features, please:

1. Check the GitHub repository for open issues
2. Review the codebase structure in src/extensions/
3. Follow existing code patterns
4. Add tests for new features
5. Update documentation

Related

• Syntax - Current syntax support
• Modes - Feature availability by mode
• C API - Programmatic API
• Examples - Usage examples