# HTML Rendering
This guide explains how HTML rendering works in `pulldown-html-ext` and how to customize the rendering process.
## Core Concepts
The HTML rendering system consists of several key components:
1. `HtmlRenderer` - The core renderer that processes Markdown events
2. `HtmlWriter` - The trait that defines how elements are rendered
3. `HtmlState` - Maintains state during rendering
4. `DefaultHtmlWriter` - The default implementation of `HtmlWriter`
## Basic Rendering
The simplest way to render Markdown to HTML:
```rust
use pulldown_cmark::Parser;
use pulldown_html_ext::{HtmlConfig, push_html};
let config = HtmlConfig::default();
let markdown = "# Hello\nThis is *markdown*";
let parser = Parser::new(markdown);
let mut output = String::new();
push_html(&mut output, parser, &config)?;
```
## Working with the Renderer Directly
For more control, you can work with the renderer directly:
```rust
use pulldown_html_ext::{create_html_renderer, DefaultHtmlWriter};
use pulldown_cmark::{Parser, Event};
use pulldown_cmark_escape::FmtWriter;
let mut output = String::new();
let writer = DefaultHtmlWriter::new(FmtWriter(&mut output), &config);
let mut renderer = create_html_renderer(writer);
let parser = Parser::new(markdown);
renderer.run(parser)?;
```
## State Management
The renderer maintains state during processing:
```rust
pub struct HtmlState {
pub numbers: Vec<u32>, // For ordered lists
pub table_state: TableContext, // Current table state
pub table_cell_index: usize, // Current cell in table
pub table_alignments: Vec<Alignment>, // Table column alignments
pub list_stack: Vec<ListContext>, // Nested list tracking
pub link_stack: Vec<LinkType>, // Nested link tracking
pub heading_stack: Vec<String>, // Header ID tracking
pub currently_in_code_block: bool, // Code block state
pub currently_in_footnote: bool, // Footnote state
}
```
## Event Handling
The renderer processes various Markdown events:
```rust
impl<W: StrWrite, H: HtmlWriter<W>> HtmlRenderer<W, H> {
pub fn run<'a, I>(&mut self, iter: I) -> Result<()>
where
I: Iterator<Item = Event<'a>>,
{
let mut iter = iter.peekable();
while let Some(event) = iter.next() {
match event {
Event::Start(tag) => self.handle_start(&mut iter, tag)?,
Event::End(tag) => self.handle_end(tag)?,
Event::Text(text) => self.writer.text(&text)?,
Event::Code(text) => self.handle_inline_code(&text)?,
Event::Html(html) => self.writer.write_str(&html)?,
Event::SoftBreak => self.writer.soft_break()?,
Event::HardBreak => self.writer.hard_break()?,
Event::Rule => self.writer.horizontal_rule()?,
Event::FootnoteReference(name) => self.writer.footnote_reference(&name)?,
Event::TaskListMarker(checked) => self.writer.task_list_item(checked)?,
Event::InlineMath(_) | Event::DisplayMath(_) | Event::InlineHtml(_) => todo!(),
}
}
Ok(())
}
}
```
## Element Handling Examples
### Headers
```rust
// Input Markdown
# Level 1
## Level 2
// Generated HTML
<h1 id="heading-1">Level 1</h1>
<h2 id="heading-2">Level 2</h2>
```
### Lists
```rust
// Input Markdown
1. First
2. Second
* Nested
* Items
// Generated HTML
<ol>
<li>First</li>
<li>Second
<ul>
<li>Nested</li>
<li>Items</li>
</ul>
</li>
</ol>
```
### Tables
```rust
// Input Markdown
| 1 | 2 | 3 |
// Generated HTML
<table>
<thead>
<tr>
<th style="text-align: left">Left</th>
<th style="text-align: center">Center</th>
<th style="text-align: right">Right</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left">1</td>
<td style="text-align: center">2</td>
<td style="text-align: right">3</td>
</tr>
</tbody>
</table>
```
## Error Handling
The renderer uses a custom error type:
```rust
pub enum HtmlError {
Io(io::Error),
Write(fmt::Error),
Theme(String),
Config(String),
Render(String),
}
```
Handle errors appropriately:
```rust
fn render_markdown(markdown: &str) -> Result<String, HtmlError> {
let config = HtmlConfig::default();
let parser = Parser::new(markdown);
let mut output = String::new();
push_html(&mut output, parser, &config)?;
Ok(output)
}
```
## Writing Output
The library supports different output methods:
```rust
// String output
let mut output = String::new();
push_html(&mut output, parser, &config)?;
// Write to formatter
write_html_fmt(&mut output, parser, &config)?;
// Write to IO
let file = File::create("output.html")?;
write_html_io(file, parser, &config)?;
```
## Best Practices
1. **State Management**
- Reset state between documents
- Check state before operations
- Handle nested structures carefully
2. **Error Handling**
- Always handle potential errors
- Use appropriate error variants
- Provide meaningful error messages
3. **Performance**
- Create Parser instances appropriately
- Reuse writers when processing multiple documents
- Consider buffer size for large documents
4. **Memory Usage**
- Clear state between documents
- Be mindful of string allocations
- Handle large documents efficiently
## Next Steps
- Learn about [Syntax Highlighting](syntax-highlighting.md)
- Implement [Custom Writers](custom-writers.md)
- See [Examples](../examples/basic-usage.md)