Skip to main content

mogwai_md/
lib.rs

1//! # mogwai-md
2//!
3//! A markdown rendering widget for [mogwai](https://github.com/schell/mogwai).
4//!
5//! `mogwai-md` parses markdown using [pulldown-cmark](https://github.com/raphlinus/pulldown-cmark)
6//! and lowers the event stream directly into a mogwai view tree. Because it
7//! builds real DOM elements (not an HTML string), the same widget works in WASM
8//! (`mogwai::web::Web`) and server-side rendering (`mogwai::ssr::Ssr`).
9//!
10//! ## Quickstart
11//!
12//! ```no_run
13//! use mogwai::prelude::*;
14//! use mogwai::web::Web;
15//! use mogwai_md::Markdown;
16//!
17//! let md = Markdown::<Web>::new("# Hello, world\n\nThis is **mogwai-md**.");
18//! mogwai::web::body().append_child(&md);
19//! ```
20//!
21//! See the `examples/demo` crate for a trunk-servable example.
22#![forbid(unsafe_code)]
23
24pub use pulldown_cmark;
25
26mod builder;
27mod inline;
28mod slug;
29
30pub use builder::{append_children, children, default_options};
31
32use mogwai::prelude::*;
33
34/// A read-only markdown rendering widget.
35///
36/// Generic over `V: View` so the same widget works in WASM
37/// (`mogwai::web::Web`) and SSR (`mogwai::ssr::Ssr`).
38///
39/// Construct with [`Markdown::new`] and update in place with
40/// [`Markdown::set_source`]. The widget is a `<div class="mogwai-md">`
41/// containing the rendered markdown as a tree of child elements.
42#[derive(ViewChild)]
43pub struct Markdown<V: View> {
44    #[child]
45    root: V::Element,
46    /// Top-level block elements appended to `root`. Tracked so
47    /// [`Markdown::set_source`] can remove them by identity before rebuilding.
48    blocks: Vec<V::Element>,
49}
50
51impl<V: View> Markdown<V> {
52    /// Render the given markdown source into a new widget.
53    ///
54    /// Uses [`default_options`] (CommonMark + GFM tables, strikethrough, task
55    /// lists). For custom options, use [`Markdown::new_with`].
56    pub fn new(src: &str) -> Self {
57        Self::new_with(src, default_options())
58    }
59
60    /// Render the given markdown source with the given parser options.
61    pub fn new_with(src: &str, opts: pulldown_cmark::Options) -> Self {
62        let root = V::Element::new("div");
63        root.set_property("class", "mogwai-md");
64        let blocks = builder::children::<V>(src, opts);
65        for block in &blocks {
66            root.append_child(block);
67        }
68        Self { root, blocks }
69    }
70
71    /// Replace the rendered content with a new markdown source.
72    ///
73    /// In v0.1 this performs a wholesale rebuild: it removes all existing child
74    /// nodes from the root `<div>` and appends a freshly parsed tree. No
75    /// diffing is performed.
76    pub fn set_source(&mut self, src: &str) {
77        self.set_source_with(src, default_options());
78    }
79
80    /// Replace the rendered content with a new source and custom options.
81    pub fn set_source_with(&mut self, src: &str, opts: pulldown_cmark::Options) {
82        for block in &self.blocks {
83            self.root.remove_child(block);
84        }
85        self.blocks = builder::children::<V>(src, opts);
86        for block in &self.blocks {
87            self.root.append_child(block);
88        }
89    }
90}
91
92impl<V: View> Default for Markdown<V> {
93    fn default() -> Self {
94        Self::new("")
95    }
96}