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}