Solutions to common issues.
Import Errors
ModuleNotFoundError: No module named 'patitas'
Cause: Patitas is not installed.
Solution:
pip install patitas
ImportError: cannot import name 'DirectiveHandler'
Cause: Directives extra not installed.
Solution:
pip install patitas[directives]
Parsing Issues
Unexpected output format
Cause: Input may have unexpected whitespace or encoding.
Solution: Check encoding and normalize:
source = source.replace('\r\n', '\n')
doc = parse(source)
Directive not recognized
Cause: Directive not registered or misspelled.
Solution: Check directive name matches exactly:
# Correct
:::{note}
Content
:::{/note}
# Wrong
:::{Note} # Case-sensitive
Rendering Issues
Empty HTML output
Cause: Source not passed to render.
Solution: Pass source for zero-copy extraction:
from patitas import parse, render
source = "# Hello"
doc = parse(source)
html = render(doc, source=source) # Include source!
Code not highlighted
Cause: Highlighter not set.
Solution: Set a highlighter:
from patitas.highlighting import set_highlighter
set_highlighter(my_highlighter)
Performance Issues
Slow parsing
Cause: Very large documents or complex nesting.
Solution: Consider splitting documents or using streaming.
High memory usage
Cause: Holding many ASTs in memory.
Solution: Process and release ASTs incrementally:
for source in sources:
doc = parse(source)
html = render(doc, source=source)
# doc is garbage collected after this iteration