Python Markdown Tables and Code Highlighting Extensions
Enable tables, fenced code blocks, and Pygments-based syntax highlighting in Python-Markdown, with configuration examples and common pitfalls.

Python's markdown package handles standard Markdown syntax, but tables and fenced code blocks are not enabled by default. To render them, add the tables and fenced_code extensions. For syntax highlighting, also enable the codehilite extension and install Pygments.
Enabling the Tables Extension
The tables extension adds support for pipe tables. A pipe table uses a header row, a separator row, and optional alignment markers.
| Name | Role |
|------|------|
| Ada | Dev |Convert it with:
import markdown
html = markdown.markdown(md_text, extensions=['tables'])The output is a standard HTML <table> with <thead> and <tbody>. Without the extension, the table syntax is treated as ordinary paragraph text and the pipes are rendered literally.
Alignment is controlled by colons in the separator row:
| Left | Center | Right |
|:-----|:------:|------:|
| a | b | c |The separator row must contain at least one dash per column, and the examples use three dashes. A pipe inside a cell must be escaped as \|.
Configuring Fenced Code Blocks
The fenced_code extension enables triple-backtick code blocks. Without it, only indented code blocks work, and backticks are treated as inline code.
```python
print("hello")
```Convert with:
html = markdown.markdown(md_text, extensions=['fenced_code'])This produces a <pre><code class="language-python"> block. The language class is derived from the info string after the opening backticks.
Adding Syntax Highlighting with CodeHilite
The codehilite extension uses Pygments to apply syntax highlighting. It works with both fenced and indented code blocks. First install Pygments:
pip install PygmentsThen enable both extensions:
html = markdown.markdown(md_text, extensions=['fenced_code', 'codehilite'])The generated HTML contains <span> elements with token classes, wrapped in a <div class="highlight">. The language is taken from the code block's info string, so a block tagged python is highlighted as Python.
If Pygments is not installed, codehilite will not produce highlighted output. The code block still renders, but without token classes.
Combining Extensions and Configuring Options
Multiple extensions can be passed in one list. Use extension_configs to control behavior.
markdown.markdown(
text,
extensions=['tables', 'fenced_code', 'codehilite'],
extension_configs={
'codehilite': {
'linenums': True,
'guess_lang': False,
'css_class': 'highlight'
}
}
)linenums adds line numbers to each code block. guess_lang attempts to detect the language when no info string is present; setting it to False avoids false positives. css_class sets the wrapper class, which is useful when you want to scope Pygments styles.
The tables extension does not require configuration in most cases. Its default behavior is sufficient for standard pipe tables.
Styling the Highlighted Output
Pygments generates HTML with semantic classes but no visual styling. You need to include a Pygments stylesheet for the colors to appear. Generate one with:
pygmentize -S default -f html -a .highlightThis prints CSS rules for the .highlight class. Include that CSS in your page, or generate a custom style with pygmentize -L styles to list available themes.
If you changed css_class, adjust the -a argument to match.
Handling Common Pitfalls
- Missing Pygments: Install Pygments or the codehilite extension will not highlight. The code block still renders, but without token spans.
- Language detection: When no language is specified,
guess_langmay mis-detect. Setguess_lang: Falseand always provide a language in fenced blocks. - Table alignment: A separator row without colons applies no alignment attribute. Colons must be placed correctly:
|:--|for left,|--:|for right,|:--:|for center. - Escaping pipes: Inside a table cell, a literal pipe must be written as
\|. - Unsanitized HTML: The
markdownpackage does not sanitize HTML. If you render user-supplied Markdown, run the output through an HTML sanitizer likebleachto prevent XSS.
Performance and Caching Considerations
Converting Markdown to HTML is CPU-bound, and syntax highlighting adds noticeable overhead because Pygments tokenizes every code block. For a documentation site or API that converts Markdown on every request, this cost repeats unnecessarily.
Cache the converted HTML keyed by the source text or its hash. If the source is static, pre-render the Markdown at build time and serve the HTML directly. For dynamic content, use an in-memory cache with a reasonable size limit.
The number of enabled extensions also affects conversion time. Only include the extensions you actually use. For example, if your documents never contain tables, omit the tables extension to reduce parsing overhead.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.