socketry_markdown/renderer/
markdown.rs

1// Released under the MIT License.
2// Copyright, 2026, by Samuel Williams.
3
4//! Markdown rendering for mdast trees.
5use super::Renderer;
6use crate::{markdown::Options, mdast::Node, message::Message};
7use alloc::string::String;
8
9/// Render an mdast tree or fragment as Markdown.
10///
11/// The default options produce standard Markdown. Use [`with_options`][Self::with_options]
12/// to configure markers and other formatting choices, or [`try_render`][Self::try_render]
13/// to handle invalid options without panicking.
14///
15/// # Example
16///
17/// ```ignore
18/// use socketry_markdown::{mdast::Node, renderer::MarkdownRenderer};
19///
20/// let node: Node = /* an mdast tree */;
21/// let mut renderer = MarkdownRenderer::new();
22/// let markdown = node.render_with(&mut renderer);
23/// ```
24#[derive(Clone, Debug, Default)]
25pub struct MarkdownRenderer {
26    options: Options,
27}
28
29impl MarkdownRenderer {
30    /// Create a Markdown renderer with default options.
31    #[must_use]
32    pub fn new() -> Self {
33        Self::default()
34    }
35
36    /// Create a Markdown renderer with custom serialization options.
37    #[must_use]
38    pub fn with_options(options: Options) -> Self {
39        Self { options }
40    }
41
42    /// Return the options used by this renderer.
43    #[must_use]
44    pub fn options(&self) -> &Options {
45        &self.options
46    }
47
48    /// Render a node, returning an error if the options are invalid.
49    ///
50    /// # Errors
51    ///
52    /// Returns an error if an option contains an invalid marker or the AST
53    /// contains a node that cannot be serialized.
54    pub fn try_render(&mut self, node: &Node) -> Result<String, Message> {
55        crate::markdown::to_markdown_with_options(node, &self.options)
56    }
57}
58
59impl Renderer for MarkdownRenderer {
60    fn render_node(&mut self, node: &Node) -> String {
61        self.try_render(node)
62            .expect("Markdown rendering failed; use try_render to handle errors")
63    }
64}
socketry_markdown/renderer/markdown.rs

socketry_markdown/renderer/
markdown.rs
