use crate::pulse::model::content::{CalloutKind, DiagramKind, SymbolBlock};
use crate::pulse::model::{Block, Inline, Linker, MarkdownOrigin, MarkdownText, Page, Site};
use pulldown_cmark::{CodeBlockKind, CowStr, Event, Options, Parser, Tag, TagEnd};
use serde::Serialize;
use std::collections::HashSet;
use std::fmt::Write as _;
use std::sync::LazyLock;
use syntect::html::{ClassStyle, ClassedHTMLGenerator, css_for_theme_with_class_style};
use syntect::parsing::SyntaxSet;
use syntect::util::LinesWithEndings;
#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct Heading {
pub depth: u8,
pub slug: String,
pub text: String,
}
#[derive(Debug, Clone, PartialEq)]
pub struct RenderedPage {
pub html: String,
pub headings: Vec<Heading>,
pub has_mermaid: bool,
}
pub fn esc(s: &str) -> String {
let mut out = String::with_capacity(s.len());
for c in s.chars() {
match c {
'&' => out.push_str("&"),
'<' => out.push_str("<"),
'>' => out.push_str(">"),
'"' => out.push_str("""),
'\'' => out.push_str("'"),
c => out.push(c),
}
}
out
}
const HL: ClassStyle = ClassStyle::SpacedPrefixed { prefix: "hl-" };
static SYNTAXES: LazyLock<SyntaxSet> = LazyLock::new(SyntaxSet::load_defaults_newlines);
pub fn highlight(code: &str, lang: &str) -> String {
let token = match lang {
"" | "text" | "txt" | "plain" | "console" | "output" => return esc(code),
"sh" | "shell" | "bash" | "zsh" => "bash",
"ts" | "typescript" | "tsx" => "js",
"yml" => "yaml",
other => other,
};
let Some(syntax) = SYNTAXES.find_syntax_by_token(token) else {
return esc(code);
};
let mut generator = ClassedHTMLGenerator::new_with_class_style(syntax, &SYNTAXES, HL);
for line in LinesWithEndings::from(code) {
if generator
.parse_html_for_line_which_includes_newline(line)
.is_err()
{
return esc(code);
}
}
generator.finalize()
}
pub fn highlight_css() -> String {
let themes = syntect::highlighting::ThemeSet::load_defaults();
let mut out = String::from("/* Generated by rfx pulse from syntect themes. */\n");
for (selector, name) in [
(":root[data-theme='light']", "InspiredGitHub"),
(":root[data-theme='dark']", "base16-ocean.dark"),
] {
let Some(theme) = themes.themes.get(name) else {
continue;
};
let Ok(css) = css_for_theme_with_class_style(theme, HL) else {
continue;
};
for line in css.lines() {
let t = line.trim_end();
if t.ends_with('{') && !t.starts_with("/*") && !t.starts_with(' ') {
let sels = t.trim_end_matches('{').trim();
let scoped: Vec<String> = sels
.split(',')
.map(|s| format!("{selector} {}", s.trim()))
.collect();
let _ = writeln!(out, "{} {{", scoped.join(", "));
} else {
let _ = writeln!(out, "{t}");
}
}
}
out
}
const HTML_ALLOW: &[&str] = &[
"<br>", "<br/>", "<br />", "<kbd>", "</kbd>", "<sub>", "</sub>", "<sup>", "</sup>",
];
struct MdOptions<'a> {
id_prefix: &'a str,
demote: u8,
toc: bool,
default_lang: &'a str,
}
pub struct Renderer<'a> {
site: &'a Site,
linker: Linker<'a>,
base: String,
}
struct PageState {
headings: Vec<Heading>,
ids: HashSet<String>,
mermaid: bool,
}
impl PageState {
fn unique(&mut self, want: &str) -> String {
let mut id = want.to_string();
let mut n = 2;
while !self.ids.insert(id.clone()) {
id = format!("{want}-{n}");
n += 1;
}
id
}
}
fn slug(text: &str) -> String {
crate::pulse::model::ids::slugify(text)
}
impl<'a> Renderer<'a> {
pub fn new(site: &'a Site, base: &str) -> Self {
Self {
site,
linker: Linker::new(site),
base: base.trim_end_matches('/').to_string(),
}
}
fn route(&self, route: &str) -> String {
format!("{}{route}", self.base)
}
fn safe_href(&self, dest: &str) -> Option<String> {
let d = dest.trim();
let lower = d.to_ascii_lowercase();
if lower.starts_with("http://")
|| lower.starts_with("https://")
|| lower.starts_with("mailto:")
|| d.starts_with('#')
{
Some(d.to_string())
} else if d.starts_with('/') && !d.starts_with("//") {
Some(self.route(d))
} else {
None
}
}
pub fn render_page(&self, page: &Page) -> RenderedPage {
let mut st = PageState {
headings: Vec::new(),
ids: HashSet::new(),
mermaid: false,
};
let mut html = String::new();
self.blocks(&page.blocks, &mut st, &mut html);
RenderedPage {
html,
headings: st.headings,
has_mermaid: st.mermaid,
}
}
fn blocks(&self, blocks: &[Block], st: &mut PageState, out: &mut String) {
for b in blocks {
self.block(b, st, out);
}
}
fn inlines(&self, inlines: &[Inline], out: &mut String) {
for i in inlines {
match i {
Inline::Text { text } => out.push_str(&esc(text)),
Inline::Code { code } => {
let _ = write!(out, "<code>{}</code>", esc(code));
}
Inline::Strong { content } => {
out.push_str("<strong>");
self.inlines(content, out);
out.push_str("</strong>");
}
Inline::Emph { content } => {
out.push_str("<em>");
self.inlines(content, out);
out.push_str("</em>");
}
Inline::Link { to, content } => match self.linker.resolve(to) {
Some(r) if r.external => {
let _ = write!(out, "<a href=\"{}\" rel=\"noopener\">", esc(&r.href));
self.inlines(content, out);
out.push_str("</a>");
}
Some(r) => {
let _ = write!(out, "<a href=\"{}\">", esc(&self.route(&r.href)));
self.inlines(content, out);
out.push_str("</a>");
}
None => self.inlines(content, out),
},
Inline::Fact { fact } => match self.site.facts.get(fact) {
Some(f) => {
let _ = write!(
out,
"<span class=\"pulse-fact\" data-fact=\"{}\">{}</span>",
esc(fact.as_str()),
esc(&f.value.display())
);
}
None => out.push('?'),
},
}
}
}
fn block(&self, b: &Block, st: &mut PageState, out: &mut String) {
match b {
Block::Heading {
level,
text,
anchor,
} => {
let l = (*level).clamp(2, 6);
let id = st.unique(anchor.as_str());
if l <= 3 {
st.headings.push(Heading {
depth: l,
slug: id.clone(),
text: text.clone(),
});
}
let _ = write!(out, "<h{l} id=\"{}\">{}</h{l}>", esc(&id), esc(text));
}
Block::Paragraph { content } => {
out.push_str("<p>");
self.inlines(content, out);
out.push_str("</p>");
}
Block::Markdown { markdown } => self.markdown_block(markdown, st, out),
Block::Code { lang, code, title } => {
out.push_str("<figure class=\"pulse-code\">");
if let Some(t) = title {
let _ = write!(out, "<figcaption>{}</figcaption>", esc(t));
}
let _ = write!(
out,
"<pre class=\"hl-code\" data-lang=\"{}\"><code>{}</code></pre></figure>",
esc(lang),
highlight(code, lang)
);
}
Block::List { ordered, items } => {
let tag = if *ordered { "ol" } else { "ul" };
let _ = write!(out, "<{tag}>");
for item in items {
out.push_str("<li>");
self.inlines(item, out);
out.push_str("</li>");
}
let _ = write!(out, "</{tag}>");
}
Block::Table { columns, rows } => {
out.push_str("<div class=\"pulse-table\"><table><thead><tr>");
for c in columns {
let _ = write!(out, "<th>{}</th>", esc(c));
}
out.push_str("</tr></thead><tbody>");
for row in rows {
out.push_str("<tr>");
for cell in row {
out.push_str("<td>");
self.inlines(cell, out);
out.push_str("</td>");
}
out.push_str("</tr>");
}
out.push_str("</tbody></table></div>");
}
Block::Callout { kind, title, body } => {
let (class, label) = match kind {
CalloutKind::Note => ("note", "Note"),
CalloutKind::Tip => ("tip", "Tip"),
CalloutKind::Caution => ("caution", "Caution"),
CalloutKind::Danger => ("danger", "Danger"),
};
let t = title.as_deref().unwrap_or(label);
let _ = write!(
out,
"<aside aria-label=\"{t}\" class=\"starlight-aside starlight-aside--{class}\"><p class=\"starlight-aside__title\" aria-hidden=\"true\">{t}</p><div class=\"starlight-aside__content\">",
t = esc(t)
);
self.blocks(body, st, out);
out.push_str("</div></aside>");
}
Block::Diagram {
kind: DiagramKind::Mermaid,
source,
links,
caption,
} => {
st.mermaid = true;
let map: serde_json::Map<String, serde_json::Value> = links
.iter()
.filter_map(|(node, t)| {
let r = self.linker.resolve(t)?;
let href = if r.external {
r.href
} else {
self.route(&r.href)
};
Some((node.clone(), serde_json::Value::String(href)))
})
.collect();
let _ = write!(
out,
"<figure class=\"pulse-diagram\"><pre class=\"pulse-mermaid\" data-links=\"{}\">{}</pre>",
esc(&serde_json::Value::Object(map).to_string()),
esc(source)
);
if let Some(c) = caption {
let _ = write!(out, "<figcaption>{}</figcaption>", esc(c));
}
out.push_str("</figure>");
}
Block::Cards { cards } => {
out.push_str("<div class=\"pulse-cards\">");
for c in cards {
let href = self.linker.resolve(&c.to).map(|r| {
if r.external {
r.href
} else {
self.route(&r.href)
}
});
let close = match &href {
Some(h) => {
let _ = write!(out, "<a class=\"pulse-card\" href=\"{}\">", esc(h));
"</a>"
}
None => {
out.push_str("<div class=\"pulse-card\">");
"</div>"
}
};
let _ = write!(
out,
"<span class=\"pulse-card-title\">{}</span>",
esc(&c.title)
);
if let Some(d) = &c.description {
let _ = write!(out, "<span class=\"pulse-card-body\">{}</span>", esc(d));
}
out.push_str(close);
}
out.push_str("</div>");
}
Block::Stats { stats } => {
out.push_str("<dl class=\"pulse-stats\">");
for s in stats {
let value = self
.site
.facts
.get(&s.fact)
.map(|f| f.value.display())
.unwrap_or_else(|| "?".into());
let _ = write!(
out,
"<div><dt>{}</dt><dd>{}</dd></div>",
esc(&s.label),
esc(&value)
);
}
out.push_str("</dl>");
}
Block::Narrative { text, fallback, .. } => match text {
Some(md) => {
out.push_str("<div class=\"pulse-narrative\" data-origin=\"llm\">");
self.markdown_block(md, st, out);
out.push_str(
"<p class=\"pulse-provenance\">Written by an LLM from facts in the index.</p></div>",
);
}
None => self.blocks(fallback, st, out),
},
Block::Symbol { symbol } => self.symbol(symbol, st, out),
}
}
fn markdown_block(&self, md: &MarkdownText, st: &mut PageState, out: &mut String) {
let opts = match md.origin {
MarkdownOrigin::Comment => MdOptions {
id_prefix: "",
demote: 0,
toc: true,
default_lang: "rust",
},
_ => MdOptions {
id_prefix: "",
demote: 0,
toc: true,
default_lang: "text",
},
};
self.markdown(&md.source, &opts, st, out);
}
fn symbol(&self, s: &SymbolBlock, st: &mut PageState, out: &mut String) {
let id = st.unique(s.anchor.as_str());
st.headings.push(Heading {
depth: 3,
slug: id.clone(),
text: s.name.clone(),
});
let _ = write!(
out,
"<section class=\"pulse-symbol\" data-kind=\"{}\"><h3 id=\"{}\"><code>{}</code><span class=\"pulse-kind\">{}</span>",
esc(&s.kind),
esc(&id),
esc(&s.name),
esc(&s.kind)
);
for badge in &s.badges {
let _ = write!(out, "<span class=\"pulse-badge\">{}</span>", esc(badge));
}
out.push_str("</h3>");
if let Some(d) = &s.deprecated {
let _ = write!(out, "<p class=\"pulse-deprecated\">{}</p>", esc(d));
}
let _ = write!(
out,
"<pre class=\"hl-code pulse-signature\" data-lang=\"{}\"><code>{}</code></pre>",
esc(&s.lang),
highlight(&s.signature, &s.lang)
);
if let Some(doc) = &s.doc {
let opts = MdOptions {
id_prefix: &format!("{id}-"),
demote: 2,
toc: false,
default_lang: if doc.origin == MarkdownOrigin::Comment {
&s.lang
} else {
"text"
},
};
out.push_str("<div class=\"pulse-doc\">");
self.markdown(&doc.source, &opts, st, out);
out.push_str("</div>");
}
let source = crate::pulse::model::Target::Source {
loc: s.source.clone(),
};
out.push_str("<p class=\"pulse-meta\">");
match self.linker.resolve(&source) {
Some(r) => {
let _ = write!(
out,
"<a href=\"{}\" rel=\"noopener\"><code>{}</code></a>",
esc(&r.href),
esc(&s.source.label())
);
}
None => {
let _ = write!(out, "<code>{}</code>", esc(&s.source.label()));
}
}
out.push_str("</p></section>");
}
fn markdown(&self, src: &str, o: &MdOptions<'_>, st: &mut PageState, out: &mut String) {
let options =
Options::ENABLE_TABLES | Options::ENABLE_STRIKETHROUGH | Options::ENABLE_TASKLISTS;
let mut events: Vec<Event> = Vec::new();
let mut code: Option<(String, String)> = None; let mut heading: Option<(u8, Vec<Event>, String)> = None; let mut image_depth = 0usize;
let mut link_open: Vec<bool> = Vec::new();
for ev in Parser::new_ext(src, options) {
if let Some((_, text)) = code.as_mut() {
match ev {
Event::Text(t) => {
text.push_str(&t);
continue;
}
Event::End(TagEnd::CodeBlock) => {
let (lang, text) = code.take().unwrap();
let html = if lang == "mermaid" {
st.mermaid = true;
format!(
"<pre class=\"pulse-mermaid\" data-links=\"{{}}\">{}</pre>",
esc(&text)
)
} else {
format!(
"<pre class=\"hl-code\" data-lang=\"{}\"><code>{}</code></pre>",
esc(&lang),
highlight(text.trim_end_matches('\n'), &lang)
)
};
events.push(Event::Html(CowStr::from(html)));
continue;
}
_ => continue,
}
}
if image_depth > 0 {
match ev {
Event::Start(Tag::Image { .. }) => image_depth += 1,
Event::End(TagEnd::Image) => {
image_depth -= 1;
if image_depth == 0 {
events.push(Event::Html(CowStr::from("]</span>")));
}
}
Event::Text(t) | Event::Code(t) => events.push(Event::Text(t)),
_ => {}
}
continue;
}
let ev = match ev {
Event::Start(Tag::CodeBlock(kind)) => {
let lang = match kind {
CodeBlockKind::Fenced(info) => info
.split(|c: char| c == ',' || c.is_whitespace())
.next()
.unwrap_or("")
.to_string(),
CodeBlockKind::Indented => String::new(),
};
let lang = if lang.is_empty() {
o.default_lang.to_string()
} else {
lang
};
code = Some((lang, String::new()));
continue;
}
Event::Start(Tag::Image { .. }) => {
image_depth = 1;
Event::Html(CowStr::from("<span class=\"pulse-image\">[image: "))
}
Event::Html(h) | Event::InlineHtml(h) => {
let t = h.trim();
if HTML_ALLOW.iter().any(|a| a.eq_ignore_ascii_case(t)) {
Event::InlineHtml(CowStr::from(t.to_ascii_lowercase()))
} else {
Event::Text(h)
}
}
Event::Start(Tag::Link {
link_type,
dest_url,
title,
id,
}) => match self.safe_href(&dest_url) {
Some(href) => {
link_open.push(true);
Event::Start(Tag::Link {
link_type,
dest_url: CowStr::from(href),
title,
id,
})
}
None => {
link_open.push(false);
continue;
}
},
Event::End(TagEnd::Link) => {
if link_open.pop().unwrap_or(false) {
Event::End(TagEnd::Link)
} else {
continue;
}
}
Event::Start(Tag::Heading { level, .. }) => {
let l = (level as u8 + o.demote).min(6);
heading = Some((l, Vec::new(), String::new()));
continue;
}
Event::End(TagEnd::Heading(_)) => {
if let Some((l, inner, text)) = heading.take() {
let id = st.unique(&format!("{}{}", o.id_prefix, slug(&text)));
if o.toc && (2..=3).contains(&l) {
st.headings.push(Heading {
depth: l,
slug: id.clone(),
text: text.clone(),
});
}
let mut inner_html = String::new();
pulldown_cmark::html::push_html(&mut inner_html, inner.into_iter());
events.push(Event::Html(CowStr::from(format!(
"<h{l} id=\"{}\">{}</h{l}>",
esc(&id),
inner_html
))));
}
continue;
}
other => other,
};
if let Some((_, inner, text)) = heading.as_mut() {
if let Event::Text(t) | Event::Code(t) = &ev {
text.push_str(t);
}
inner.push(ev);
continue;
}
events.push(ev);
}
pulldown_cmark::html::push_html(out, events.into_iter());
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::pulse::model::{
BuildReport, FactStore, MarkdownOrigin, PageId, PageKind, SCHEMA_VERSION, SiteMeta, TabId,
};
use std::collections::BTreeMap;
fn site_with(blocks: Vec<Block>) -> Site {
let page = Page {
id: PageId::new("p"),
tab: TabId::Docs,
kind: PageKind::Changelog,
title: "P".into(),
description: None,
route: "/docs/p/".into(),
badges: vec![],
blocks,
};
Site {
schema_version: SCHEMA_VERSION,
meta: SiteMeta {
title: "T".into(),
description: None,
repo: None,
generator: "test".into(),
},
tabs: vec![],
pages: BTreeMap::from([(PageId::new("p"), page)]),
symbols: BTreeMap::new(),
facts: FactStore::default(),
report: BuildReport::default(),
evidence: BTreeMap::new(),
known_names: Vec::new(),
}
}
fn md(src: &str) -> String {
let site = site_with(vec![Block::Markdown {
markdown: MarkdownText {
source: src.into(),
origin: MarkdownOrigin::Comment,
from: None,
},
}]);
Renderer::new(&site, "/reflex/")
.render_page(&site.pages[&PageId::new("p")])
.html
}
#[test]
fn raw_html_and_scripts_become_text() {
let h = md(
"Uses `Vec<String>` and <T> and {x}.\n\n<script>alert(1)</script>\n\n<!-- hidden -->\n\nA<br>B <kbd>Ctrl</kbd>",
);
assert!(h.contains("<code>Vec<String></code>"), "{h}");
assert!(h.contains("<T>"), "{h}");
assert!(!h.contains("<script"), "{h}");
assert!(h.contains("<script>"), "{h}");
assert!(h.contains("<!-- hidden -->"), "{h}");
assert!(h.contains("<br>") && h.contains("<kbd>Ctrl</kbd>"), "{h}");
assert!(h.contains("{x}"));
}
#[test]
fn links_are_sanitised_and_prefixed() {
let h = md(
"[a](javascript:alert(1)) [b](https://x.dev) [c](/docs/q/#m) [d](data:text/html,x) [e](docs/API.md) ",
);
assert!(!h.contains("javascript:"), "{h}");
assert!(!h.contains("data:"), "{h}");
assert!(h.contains("href=\"https://x.dev\""), "{h}");
assert!(h.contains("href=\"/reflex/docs/q/#m\""), "{h}");
assert!(h.starts_with("<p>a <a"), "unsafe link keeps its text: {h}");
assert!(h.contains("[image: logo]"), "{h}");
assert!(!h.contains("<img"), "{h}");
}
#[test]
fn code_is_highlighted_and_mermaid_kept() {
let h = md(
"```\nlet x = 1;\n```\n\n```mermaid\ngraph LR; a-->b\n```\n\n```text\n--json <b>\n```",
);
assert!(
h.contains("data-lang=\"rust\""),
"bare fence in a doc comment is rust: {h}"
);
assert!(h.contains("hl-"), "{h}");
assert!(h.contains("<pre class=\"pulse-mermaid\""), "{h}");
assert!(h.contains("a-->b"), "{h}");
assert!(
h.contains("--json <b>"),
"no smart punctuation, escaped: {h}"
);
}
#[test]
fn headings_get_unique_ids_and_toc_entries() {
let site = site_with(vec![
Block::heading(2, "Errors"),
Block::Markdown {
markdown: MarkdownText {
source: "## Errors\n\ntext".into(),
origin: MarkdownOrigin::Doc,
from: None,
},
},
]);
let r = Renderer::new(&site, "").render_page(&site.pages[&PageId::new("p")]);
let ids: Vec<&str> = r.headings.iter().map(|h| h.slug.as_str()).collect();
assert_eq!(ids, vec!["errors", "errors-2"]);
}
#[test]
fn highlight_css_covers_both_themes() {
let css = highlight_css();
assert!(
css.contains(":root[data-theme='light'] .hl-"),
"{}",
&css[..200.min(css.len())]
);
assert!(css.contains(":root[data-theme='dark'] .hl-"));
}
}