813 lines
29 KiB
Rust
813 lines
29 KiB
Rust
//! A small Markdown renderer for the concept documents.
|
|
//!
|
|
//! The renderer covers the subset of Markdown the content uses. It is not a
|
|
//! general implementation of the CommonMark specification; it is the
|
|
//! smallest renderer that expresses the documents, and it is written here
|
|
//! because the service may not depend on a crate.
|
|
//!
|
|
//! Supported constructs:
|
|
//!
|
|
//! - ATX headings, `#` through `######`
|
|
//! - paragraphs, with soft line breaks joined by a space
|
|
//! - fenced code blocks delimited by three backticks, with an optional
|
|
//! language name
|
|
//! - pipe tables with a delimiter row, where a cell may end with `^` to
|
|
//! mark it as right aligned
|
|
//! - unordered lists marked with `-` and ordered lists marked with `1.`
|
|
//! - block quotes marked with `>`
|
|
//! - thematic breaks written as `---`
|
|
//! - inline emphasis `*text*` and strong emphasis `**text**`
|
|
//! - inline code spans delimited by backticks
|
|
//! - links written as `[text](url)`
|
|
//!
|
|
//! A link whose target is a Rust path, such as `[Epoch](crate::Epoch)`,
|
|
//! names an item of the library rather than a web address. Such a link is
|
|
//! rendered as a link to the interface page of the item, so that a doc
|
|
//! comment can cross reference another item the way `rustdoc` does.
|
|
//! - concept cross references written as `[[id]]` or `[[id|label]]`, which
|
|
//! render as a link with a `data-concept` attribute so the frontend can
|
|
//! route them without a page load
|
|
//!
|
|
//! Every text node is escaped, so a document cannot inject markup. The only
|
|
//! HTML the renderer emits is the markup it generates itself.
|
|
|
|
/// Renders a Markdown document to HTML.
|
|
pub fn render(markdown: &str) -> String {
|
|
render_with(markdown, None)
|
|
}
|
|
|
|
/// Renders a Markdown document, resolving a link to a library item.
|
|
///
|
|
/// `items` is the set of item names the interface catalog contains. A
|
|
/// shortcut link whose name is not in the set is left as a code span, so a
|
|
/// doc comment can write `[`0, 1`]` without producing a link to nothing.
|
|
pub fn render_with(markdown: &str, items: Option<&std::collections::HashSet<String>>) -> String {
|
|
let lines: Vec<&str> = markdown.lines().collect();
|
|
let mut output = String::with_capacity(markdown.len() + markdown.len() / 2);
|
|
let mut index = 0;
|
|
|
|
while index < lines.len() {
|
|
let line = lines[index];
|
|
let trimmed = line.trim_end();
|
|
|
|
if trimmed.trim().is_empty() {
|
|
index += 1;
|
|
continue;
|
|
}
|
|
|
|
if let Some(language) = fence_language(trimmed) {
|
|
index += 1;
|
|
let mut code = String::new();
|
|
while index < lines.len() && !lines[index].trim_start().starts_with("```") {
|
|
code.push_str(lines[index]);
|
|
code.push('\n');
|
|
index += 1;
|
|
}
|
|
index += 1; // closing fence
|
|
output.push_str(&render_code_block(language, &code));
|
|
continue;
|
|
}
|
|
|
|
if let Some(level) = heading_level(trimmed) {
|
|
let text = trimmed[level..].trim();
|
|
let id = slug(text);
|
|
output.push_str(&format!(
|
|
"<h{level} id=\"{}\">{}<a class=\"anchor\" href=\"#{id}\" aria-hidden=\"true\">#</a></h{level}>\n",
|
|
escape(&id),
|
|
inline_items(text, items),
|
|
));
|
|
index += 1;
|
|
continue;
|
|
}
|
|
|
|
if is_thematic_break(trimmed) {
|
|
output.push_str("<hr>\n");
|
|
index += 1;
|
|
continue;
|
|
}
|
|
|
|
if trimmed.starts_with('|') {
|
|
let (block, next) = collect_table(&lines, index);
|
|
output.push_str(&render_table(&block, items));
|
|
index = next;
|
|
continue;
|
|
}
|
|
|
|
if trimmed.starts_with("> ") || trimmed == ">" {
|
|
let (block, next) =
|
|
collect_while(&lines, index, |line| line.trim_start().starts_with('>'));
|
|
let inner: Vec<&str> = block
|
|
.iter()
|
|
.map(|line| line.trim_start().trim_start_matches('>').trim_start())
|
|
.collect();
|
|
output.push_str("<blockquote>\n");
|
|
output.push_str(&render_with(&inner.join("\n"), items));
|
|
output.push_str("</blockquote>\n");
|
|
index = next;
|
|
continue;
|
|
}
|
|
|
|
if is_unordered_item(trimmed) {
|
|
let (block, next) =
|
|
collect_while(&lines, index, |line| is_unordered_item(line.trim_end()));
|
|
output.push_str(&render_list(&block, false, items));
|
|
index = next;
|
|
continue;
|
|
}
|
|
|
|
if is_ordered_item(trimmed) {
|
|
let (block, next) =
|
|
collect_while(&lines, index, |line| is_ordered_item(line.trim_end()));
|
|
output.push_str(&render_list(&block, true, items));
|
|
index = next;
|
|
continue;
|
|
}
|
|
|
|
// A paragraph runs until a blank line or the start of another block.
|
|
let (block, next) = collect_while(&lines, index, |line| {
|
|
let trimmed = line.trim_end();
|
|
!trimmed.trim().is_empty()
|
|
&& fence_language(trimmed).is_none()
|
|
&& heading_level(trimmed).is_none()
|
|
&& !trimmed.starts_with('|')
|
|
&& !trimmed.starts_with("> ")
|
|
&& !is_thematic_break(trimmed)
|
|
&& !is_unordered_item(trimmed)
|
|
&& !is_ordered_item(trimmed)
|
|
});
|
|
let text = block
|
|
.iter()
|
|
.map(|line| line.trim())
|
|
.collect::<Vec<_>>()
|
|
.join(" ");
|
|
output.push_str(&format!("<p>{}</p>\n", inline_items(&text, items)));
|
|
index = next;
|
|
}
|
|
|
|
output
|
|
}
|
|
|
|
/// Returns the language of a fence line, or `None` when the line is not a
|
|
/// fence.
|
|
fn fence_language(line: &str) -> Option<&str> {
|
|
let trimmed = line.trim_start();
|
|
let rest = trimmed.strip_prefix("```")?;
|
|
Some(rest.trim())
|
|
}
|
|
|
|
/// Returns the heading level of a line, or `None` when it is not a heading.
|
|
fn heading_level(line: &str) -> Option<usize> {
|
|
let mut level = 0;
|
|
for character in line.chars() {
|
|
if character == '#' {
|
|
level += 1;
|
|
} else {
|
|
break;
|
|
}
|
|
}
|
|
if (1..=6).contains(&level) && line[level..].starts_with(' ') {
|
|
Some(level)
|
|
} else {
|
|
None
|
|
}
|
|
}
|
|
|
|
/// Returns `true` when a line is a thematic break.
|
|
fn is_thematic_break(line: &str) -> bool {
|
|
let trimmed = line.trim();
|
|
trimmed.len() >= 3 && trimmed.chars().all(|character| character == '-')
|
|
}
|
|
|
|
/// Returns `true` when a line opens an unordered list item.
|
|
fn is_unordered_item(line: &str) -> bool {
|
|
let trimmed = line.trim_start();
|
|
trimmed.starts_with("- ") || trimmed == "-"
|
|
}
|
|
|
|
/// Returns `true` when a line opens an ordered list item.
|
|
fn is_ordered_item(line: &str) -> bool {
|
|
let trimmed = line.trim_start();
|
|
let digits: String = trimmed.chars().take_while(char::is_ascii_digit).collect();
|
|
!digits.is_empty() && trimmed[digits.len()..].starts_with(". ")
|
|
}
|
|
|
|
/// Collects lines while `predicate` holds.
|
|
fn collect_while<'a, F>(lines: &[&'a str], start: usize, predicate: F) -> (Vec<&'a str>, usize)
|
|
where
|
|
F: Fn(&str) -> bool,
|
|
{
|
|
let mut block = Vec::new();
|
|
let mut index = start;
|
|
while index < lines.len() && predicate(lines[index]) {
|
|
block.push(lines[index]);
|
|
index += 1;
|
|
}
|
|
(block, index)
|
|
}
|
|
|
|
/// Collects the lines of a table, which includes the delimiter row.
|
|
fn collect_table<'a>(lines: &[&'a str], start: usize) -> (Vec<&'a str>, usize) {
|
|
collect_while(lines, start, |line| {
|
|
let trimmed = line.trim_end();
|
|
trimmed.starts_with('|') && !trimmed.trim().is_empty()
|
|
})
|
|
}
|
|
|
|
/// Renders a fenced code block.
|
|
fn render_code_block(language: &str, code: &str) -> String {
|
|
let class = if language.is_empty() {
|
|
String::new()
|
|
} else {
|
|
format!(" class=\"language-{}\"", escape(language))
|
|
};
|
|
format!(
|
|
"<figure class=\"code\"><figcaption>{}</figcaption><pre><code{}>{}</code></pre></figure>\n",
|
|
if language.is_empty() {
|
|
"text"
|
|
} else {
|
|
language
|
|
},
|
|
class,
|
|
escape(code),
|
|
)
|
|
}
|
|
|
|
/// Renders a pipe table.
|
|
///
|
|
/// The first row is the header, the second row is the delimiter that marks
|
|
/// the table, and the remaining rows are the body. A cell whose content ends
|
|
/// with `^` is aligned to the right, which is used for numeric columns.
|
|
fn render_table(block: &[&str], items: Option<&std::collections::HashSet<String>>) -> String {
|
|
if block.len() < 2 {
|
|
return String::new();
|
|
}
|
|
let header = split_row(block[0]);
|
|
let aligns: Vec<bool> = split_row(block[1])
|
|
.iter()
|
|
.map(|cell| cell.trim().ends_with('^'))
|
|
.collect();
|
|
|
|
let mut output = String::from("<div class=\"table-wrap\"><table>\n<thead>\n<tr>");
|
|
for (index, cell) in header.iter().enumerate() {
|
|
let align = aligns.get(index).copied().unwrap_or(false);
|
|
output.push_str("<th");
|
|
if align {
|
|
output.push_str(" class=\"numeric\"");
|
|
}
|
|
output.push('>');
|
|
output.push_str(&inline_items(cell.trim().trim_end_matches('^'), items));
|
|
output.push_str("</th>");
|
|
}
|
|
output.push_str("</tr>\n</thead>\n<tbody>\n");
|
|
for row in &block[2..] {
|
|
output.push_str("<tr>");
|
|
for (index, cell) in split_row(row).iter().enumerate() {
|
|
let align = aligns.get(index).copied().unwrap_or(false);
|
|
output.push_str("<td");
|
|
if align {
|
|
output.push_str(" class=\"numeric\"");
|
|
}
|
|
output.push('>');
|
|
output.push_str(&inline_items(cell.trim().trim_end_matches('^'), items));
|
|
output.push_str("</td>");
|
|
}
|
|
output.push_str("</tr>\n");
|
|
}
|
|
output.push_str("</tbody>\n</table></div>\n");
|
|
output
|
|
}
|
|
|
|
/// Splits a table row into its cells.
|
|
fn split_row(row: &str) -> Vec<String> {
|
|
let trimmed = row.trim().trim_start_matches('|').trim_end_matches('|');
|
|
trimmed.split('|').map(str::to_string).collect()
|
|
}
|
|
|
|
/// Renders a list.
|
|
fn render_list(
|
|
block: &[&str],
|
|
ordered: bool,
|
|
items: Option<&std::collections::HashSet<String>>,
|
|
) -> String {
|
|
let tag = if ordered { "ol" } else { "ul" };
|
|
let mut output = format!("<{tag}>\n");
|
|
for line in block {
|
|
let trimmed = line.trim_start();
|
|
let content = if ordered {
|
|
let digits: String = trimmed.chars().take_while(char::is_ascii_digit).collect();
|
|
trimmed[digits.len() + 2..].to_string()
|
|
} else {
|
|
trimmed[2..].to_string()
|
|
};
|
|
output.push_str(&format!("<li>{}</li>\n", inline_items(&content, items)));
|
|
}
|
|
output.push_str(&format!("</{tag}>\n"));
|
|
output
|
|
}
|
|
|
|
/// Renders inline markup within a block of text.
|
|
///
|
|
/// The scan is single pass. A backtick span ends at the next backtick, a
|
|
/// link ends at its closing parenthesis, and a cross reference ends at its
|
|
/// closing bracket; anything unmatched is left as literal text.
|
|
#[allow(dead_code)]
|
|
fn inline(text: &str) -> String {
|
|
inline_items(text, None)
|
|
}
|
|
|
|
/// Renders inline markup, resolving a shortcut link against `items`.
|
|
fn inline_items(text: &str, items: Option<&std::collections::HashSet<String>>) -> String {
|
|
let characters: Vec<char> = text.chars().collect();
|
|
let mut output = String::with_capacity(text.len());
|
|
let mut index = 0;
|
|
|
|
while index < characters.len() {
|
|
let character = characters[index];
|
|
|
|
if character == '`' {
|
|
if let Some(end) = find(&characters, index + 1, '`') {
|
|
let code: String = characters[index + 1..end].iter().collect();
|
|
output.push_str("<code>");
|
|
output.push_str(&escape(&code));
|
|
output.push_str("</code>");
|
|
index = end + 1;
|
|
continue;
|
|
}
|
|
}
|
|
|
|
if character == '[' && characters.get(index + 1) == Some(&'[') {
|
|
if let Some(end) = find_pair(&characters, index + 2) {
|
|
let inner: String = characters[index + 2..end].iter().collect();
|
|
output.push_str(&render_concept_link(&inner, items));
|
|
index = end + 2;
|
|
continue;
|
|
}
|
|
}
|
|
|
|
// A shortcut link, `[`Name`]`, is how a doc comment refers to
|
|
// another item without repeating the path. It is rendered as a link
|
|
// to the item page when the inner text names a plausible item.
|
|
if character == '[' && characters.get(index + 1) == Some(&'`') {
|
|
if let Some((label, end)) = parse_shortcut_link(&characters, index) {
|
|
if let Some(item) = shortcut_item(&label, items) {
|
|
output.push_str(&format!(
|
|
"<a class=\"api-link\" data-api=\"{}\" href=\"#/api/{}\"><code>{}</code></a>",
|
|
escape_attr(item),
|
|
escape_attr(item),
|
|
escape(&label),
|
|
));
|
|
index = end;
|
|
continue;
|
|
}
|
|
}
|
|
}
|
|
|
|
if character == '[' {
|
|
if let Some((label, url, end)) = parse_link(&characters, index) {
|
|
match rust_path_target(&url, items) {
|
|
// A link to a library item becomes a link to the item
|
|
// page, which is where the reader can see the signature
|
|
// and the rest of the documentation.
|
|
Some(item) => output.push_str(&format!(
|
|
"<a class=\"api-link\" data-api=\"{}\" href=\"#/api/{}\">{}</a>",
|
|
escape_attr(&item),
|
|
escape_attr(&item),
|
|
inline_items(&label, items),
|
|
)),
|
|
None => output.push_str(&format!(
|
|
"<a href=\"{}\">{}</a>",
|
|
escape_attr(&url),
|
|
inline_items(&label, items),
|
|
)),
|
|
}
|
|
index = end;
|
|
continue;
|
|
}
|
|
}
|
|
|
|
if character == '*' {
|
|
if characters.get(index + 1) == Some(&'*') {
|
|
if let Some(end) = find_double(&characters, index + 2) {
|
|
let strong: String = characters[index + 2..end].iter().collect();
|
|
output.push_str(&format!(
|
|
"<strong>{}</strong>",
|
|
inline_items(&strong, items)
|
|
));
|
|
index = end + 2;
|
|
continue;
|
|
}
|
|
} else if let Some(end) = find(&characters, index + 1, '*') {
|
|
if end > index + 1 {
|
|
let emphasis: String = characters[index + 1..end].iter().collect();
|
|
output.push_str(&format!("<em>{}</em>", inline_items(&emphasis, items)));
|
|
index = end + 1;
|
|
continue;
|
|
}
|
|
}
|
|
}
|
|
|
|
match character {
|
|
'&' => output.push_str("&"),
|
|
'<' => output.push_str("<"),
|
|
'>' => output.push_str(">"),
|
|
'"' => output.push_str("""),
|
|
other => output.push(other),
|
|
}
|
|
index += 1;
|
|
}
|
|
|
|
output
|
|
}
|
|
|
|
/// Finds the next occurrence of `needle` at or after `start`.
|
|
fn find(characters: &[char], start: usize, needle: char) -> Option<usize> {
|
|
(start..characters.len()).find(|index| characters[*index] == needle)
|
|
}
|
|
|
|
/// Finds the next `]]` at or after `start`.
|
|
fn find_pair(characters: &[char], start: usize) -> Option<usize> {
|
|
(start..characters.len().saturating_sub(1))
|
|
.find(|index| characters[*index] == ']' && characters[*index + 1] == ']')
|
|
}
|
|
|
|
/// Finds the next `**` at or after `start`.
|
|
fn find_double(characters: &[char], start: usize) -> Option<usize> {
|
|
(start..characters.len().saturating_sub(1))
|
|
.find(|index| characters[*index] == '*' && characters[*index + 1] == '*')
|
|
}
|
|
|
|
/// Parses a shortcut link, `[`text`]`, starting at `start`.
|
|
///
|
|
/// Returns the text between the backticks and the index just past the
|
|
/// closing bracket.
|
|
fn parse_shortcut_link(characters: &[char], start: usize) -> Option<(String, usize)> {
|
|
if characters.get(start) != Some(&'[') || characters.get(start + 1) != Some(&'`') {
|
|
return None;
|
|
}
|
|
let tick = find(characters, start + 2, '`')?;
|
|
if characters.get(tick + 1) != Some(&']') {
|
|
return None;
|
|
}
|
|
let label: String = characters[start + 2..tick].iter().collect();
|
|
Some((label, tick + 2))
|
|
}
|
|
|
|
/// Returns the item name a shortcut link refers to.
|
|
///
|
|
/// A shortcut link names an item, optionally with a module path or a
|
|
/// method, such as `Epoch::mjd` or `apsis_time::Epoch`. The item page
|
|
/// routes on the item name, so the last segment is used. A label that is
|
|
/// not a plausible item name, such as `0, 1` or `-pi/2, pi/2`, is not a
|
|
/// link and returns `None`.
|
|
fn shortcut_item<'a>(
|
|
label: &'a str,
|
|
items: Option<&std::collections::HashSet<String>>,
|
|
) -> Option<&'a str> {
|
|
let name = label.rsplit("::").next()?.trim();
|
|
let is_name = !name.is_empty()
|
|
&& name
|
|
.chars()
|
|
.all(|character| character.is_alphanumeric() || character == '_');
|
|
if !is_name {
|
|
return None;
|
|
}
|
|
// When the catalog is available the name must be an item of the
|
|
// library, which is what keeps a label such as `0, 1` or a phrase from
|
|
// becoming a link. Without it, a name that starts with an upper case
|
|
// letter is taken as an item, which is the correct guess for a doc
|
|
// comment that names another item.
|
|
match items {
|
|
Some(items) => items.contains(name).then_some(name),
|
|
None => name
|
|
.chars()
|
|
.next()
|
|
.is_some_and(char::is_uppercase)
|
|
.then_some(name),
|
|
}
|
|
}
|
|
|
|
/// Returns the item name of a Rust path written as a link target.
|
|
///
|
|
/// A doc comment links to a library item with a Rust path, such as
|
|
/// `crate::Epoch`, `core::result::Result`, or `f64::rem_euclid`. The name
|
|
/// the interface page routes on is the last segment of the path, with any
|
|
/// generic arguments removed. A target that is a web address or a fragment
|
|
/// is not a Rust path and returns `None`, which leaves the link as written.
|
|
///
|
|
/// A path may end in a variant or a method rather than the item itself,
|
|
/// such as `crate::PropagationErrorKind::Decayed`. The resolver walks the
|
|
/// path from the right and returns the first segment that is a known item,
|
|
/// so such a link points at the enum or the trait that declares it.
|
|
fn rust_path_target(
|
|
url: &str,
|
|
items: Option<&std::collections::HashSet<String>>,
|
|
) -> Option<String> {
|
|
if url.is_empty() || url.contains('/') || url.starts_with('#') {
|
|
return None;
|
|
}
|
|
let segments: Vec<&str> = url
|
|
.split("::")
|
|
.map(|segment| segment.split(['<', '(']).next().unwrap_or("").trim())
|
|
.filter(|segment| !segment.is_empty())
|
|
.collect();
|
|
if segments.is_empty() {
|
|
return None;
|
|
}
|
|
let is_rust_path =
|
|
segments.len() > 1 || segments[0].chars().next().is_some_and(char::is_uppercase);
|
|
if !is_rust_path {
|
|
return None;
|
|
}
|
|
let is_name = |segment: &str| {
|
|
!segment.is_empty()
|
|
&& segment
|
|
.chars()
|
|
.all(|character| character.is_alphanumeric() || character == '_')
|
|
};
|
|
match items {
|
|
Some(items) => segments
|
|
.iter()
|
|
.rev()
|
|
.find(|segment| is_name(segment) && items.contains(**segment))
|
|
.map(|segment| (*segment).to_string()),
|
|
None => segments
|
|
.iter()
|
|
.rev()
|
|
.find(|segment| is_name(segment))
|
|
.map(|segment| (*segment).to_string()),
|
|
}
|
|
}
|
|
|
|
/// Parses a `[label](url)` link starting at `start`, returning the label,
|
|
/// the URL, and the index just past the link.
|
|
fn parse_link(characters: &[char], start: usize) -> Option<(String, String, usize)> {
|
|
if characters.get(start) != Some(&'[') {
|
|
return None;
|
|
}
|
|
let label_end = find(characters, start + 1, ']')?;
|
|
if characters.get(label_end + 1) != Some(&'(') {
|
|
return None;
|
|
}
|
|
let url_end = find(characters, label_end + 2, ')')?;
|
|
let label: String = characters[start + 1..label_end].iter().collect();
|
|
let url: String = characters[label_end + 2..url_end].iter().collect();
|
|
Some((label, url, url_end + 1))
|
|
}
|
|
|
|
/// Renders a concept cross reference.
|
|
///
|
|
/// The argument is either `id` or `id|label`. An identifier that is not a
|
|
/// plausible identifier is rendered as literal text, so a stray `[[` in the
|
|
/// prose cannot produce a broken link.
|
|
fn render_concept_link(inner: &str, items: Option<&std::collections::HashSet<String>>) -> String {
|
|
let (id, label) = match inner.split_once('|') {
|
|
Some((id, label)) => (id.trim(), label.trim()),
|
|
None => (inner.trim(), inner.trim()),
|
|
};
|
|
if id.is_empty()
|
|
|| !id
|
|
.chars()
|
|
.all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
|
|
{
|
|
return format!("[[{}]]", escape(inner));
|
|
}
|
|
format!(
|
|
"<a class=\"concept-link\" data-concept=\"{}\" href=\"#/concept/{}\">{}</a>",
|
|
escape_attr(id),
|
|
escape_attr(id),
|
|
inline_items(label, items),
|
|
)
|
|
}
|
|
|
|
/// Escapes text for use in an HTML text node.
|
|
fn escape(text: &str) -> String {
|
|
let mut output = String::with_capacity(text.len());
|
|
for character in text.chars() {
|
|
match character {
|
|
'&' => output.push_str("&"),
|
|
'<' => output.push_str("<"),
|
|
'>' => output.push_str(">"),
|
|
'"' => output.push_str("""),
|
|
'\'' => output.push_str("'"),
|
|
other => output.push(other),
|
|
}
|
|
}
|
|
output
|
|
}
|
|
|
|
/// Escapes text for use inside a double quoted attribute.
|
|
///
|
|
/// Only the characters that can end the attribute or start an entity are
|
|
/// escaped; the value never contains a quote because identifiers are
|
|
/// restricted by [`render_concept_link`] and links are escaped here too.
|
|
fn escape_attr(text: &str) -> String {
|
|
escape(text)
|
|
}
|
|
|
|
/// Returns a URL friendly slug for a heading.
|
|
fn slug(text: &str) -> String {
|
|
let mut slug = String::with_capacity(text.len());
|
|
let mut last_dash = true;
|
|
for character in text.chars() {
|
|
if character.is_ascii_alphanumeric() {
|
|
slug.push(character.to_ascii_lowercase());
|
|
last_dash = false;
|
|
} else if !last_dash {
|
|
slug.push('-');
|
|
last_dash = true;
|
|
}
|
|
}
|
|
while slug.ends_with('-') {
|
|
slug.pop();
|
|
}
|
|
if slug.is_empty() {
|
|
slug.push_str("section");
|
|
}
|
|
slug
|
|
}
|
|
|
|
/// Strips Markdown markup from text, leaving readable plain text.
|
|
///
|
|
/// This is used to build the search index, where markup would only add
|
|
/// noise. Cross references keep their label, links keep their text, and
|
|
/// code spans keep their content.
|
|
pub fn to_plain_text(markdown: &str) -> String {
|
|
let mut output = String::with_capacity(markdown.len());
|
|
for line in markdown.lines() {
|
|
let trimmed = line.trim();
|
|
if trimmed.starts_with("```") || trimmed.is_empty() {
|
|
continue;
|
|
}
|
|
let mut text = trimmed.to_string();
|
|
if let Some(level) = heading_level(&text) {
|
|
text = text[level..].trim().to_string();
|
|
}
|
|
if text.starts_with('|') {
|
|
text = split_row(&text)
|
|
.iter()
|
|
.map(|cell| cell.trim().trim_end_matches('^').to_string())
|
|
.filter(|cell| !cell.is_empty() && !cell.chars().all(|c| c == '-'))
|
|
.collect::<Vec<_>>()
|
|
.join(" ");
|
|
}
|
|
let text = text.trim_start_matches(['>', '-', ' ']).trim().to_string();
|
|
output.push_str(&strip_inline(&text));
|
|
output.push(' ');
|
|
}
|
|
output
|
|
}
|
|
|
|
/// Removes inline markup from a single line.
|
|
fn strip_inline(text: &str) -> String {
|
|
let characters: Vec<char> = text.chars().collect();
|
|
let mut output = String::with_capacity(text.len());
|
|
let mut index = 0;
|
|
while index < characters.len() {
|
|
let character = characters[index];
|
|
if character == '`' {
|
|
if let Some(end) = find(&characters, index + 1, '`') {
|
|
output.extend(&characters[index + 1..end]);
|
|
index = end + 1;
|
|
continue;
|
|
}
|
|
}
|
|
if character == '[' && characters.get(index + 1) == Some(&'[') {
|
|
if let Some(end) = find_pair(&characters, index + 2) {
|
|
let inner: String = characters[index + 2..end].iter().collect();
|
|
let label = inner
|
|
.split_once('|')
|
|
.map(|(_, label)| label)
|
|
.unwrap_or(&inner);
|
|
output.push_str(label);
|
|
index = end + 2;
|
|
continue;
|
|
}
|
|
}
|
|
if character == '[' {
|
|
if let Some((label, _, end)) = parse_link(&characters, index) {
|
|
output.push_str(&label);
|
|
index = end;
|
|
continue;
|
|
}
|
|
}
|
|
if character == '*' {
|
|
index += 1;
|
|
continue;
|
|
}
|
|
output.push(character);
|
|
index += 1;
|
|
}
|
|
output
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
|
|
#[test]
|
|
fn renders_headings_and_paragraphs() {
|
|
let html = render("# Title\n\nSome *text* and **more**.\n");
|
|
assert!(html.contains("<h1 id=\"title\">Title"));
|
|
assert!(html.contains("<p>Some <em>text</em> and <strong>more</strong>.</p>"));
|
|
}
|
|
|
|
#[test]
|
|
fn renders_tables_with_alignment() {
|
|
let markdown = "| a | b |\n|---|---|\n| 1 | 2 |\n";
|
|
let html = render(markdown);
|
|
assert!(html.contains("<th>a</th>"));
|
|
assert!(html.contains("<td>1</td>"));
|
|
}
|
|
|
|
#[test]
|
|
fn escapes_code_and_text() {
|
|
let html = render("Use `a < b` and <script>.\n");
|
|
assert!(html.contains("<code>a < b</code>"));
|
|
assert!(html.contains("<script>"));
|
|
assert!(!html.contains("<script>"));
|
|
}
|
|
|
|
#[test]
|
|
fn a_rust_path_link_points_at_the_interface_page() {
|
|
let html = render("Returns [`Epoch`](crate::Epoch) and [more](https://example.com).\n");
|
|
assert!(html.contains("data-api=\"Epoch\""), "{html}");
|
|
assert!(html.contains("href=\"#/api/Epoch\""), "{html}");
|
|
// A web address is left as it is.
|
|
assert!(html.contains("href=\"https://example.com\""), "{html}");
|
|
}
|
|
|
|
#[test]
|
|
fn a_path_to_a_variant_resolves_to_the_declaring_item() {
|
|
let known: std::collections::HashSet<String> = ["PropagationErrorKind"]
|
|
.iter()
|
|
.map(|n| n.to_string())
|
|
.collect();
|
|
let html = render_with(
|
|
"Returns [`Decayed`](crate::PropagationErrorKind::Decayed).\n",
|
|
Some(&known),
|
|
);
|
|
assert!(html.contains("data-api=\"PropagationErrorKind\""), "{html}");
|
|
// A path whose segments are all unknown is left as written.
|
|
let html = render_with("[`Nope`](crate::Unknown::Missing).\n", Some(&known));
|
|
assert!(!html.contains("data-api"), "{html}");
|
|
}
|
|
|
|
/// The names of two items, for the shortcut link test.
|
|
fn items() -> std::collections::HashSet<String> {
|
|
["mjd", "Epoch"]
|
|
.iter()
|
|
.map(|name| name.to_string())
|
|
.collect()
|
|
}
|
|
|
|
#[test]
|
|
fn a_shortcut_link_points_at_the_interface_page() {
|
|
let known = items();
|
|
let html = render_with(
|
|
"See [`Epoch::mjd`] and [`apsis_time::Epoch`].\n",
|
|
Some(&known),
|
|
);
|
|
assert!(html.contains("data-api=\"mjd\""), "{html}");
|
|
assert!(html.contains("href=\"#/api/mjd\""), "{html}");
|
|
assert!(html.contains("data-api=\"Epoch\""), "{html}");
|
|
// A label that is not an item name stays as a code span.
|
|
let html = render_with("The range is [`0, 1`].\n", Some(&known));
|
|
assert!(!html.contains("data-api"), "{html}");
|
|
assert!(html.contains("<code>0, 1</code>"), "{html}");
|
|
// A name that is not in the catalog also stays as a code span.
|
|
let html = render_with("See [`NotAnItem`].\n", Some(&known));
|
|
assert!(!html.contains("data-api"), "{html}");
|
|
}
|
|
|
|
#[test]
|
|
fn renders_concept_links() {
|
|
let html = render("See [[sgp4]] and [[tle|the element set]].\n");
|
|
assert!(html.contains("data-concept=\"sgp4\""));
|
|
assert!(html.contains(">the element set</a>"));
|
|
}
|
|
|
|
#[test]
|
|
fn renders_code_blocks_with_language() {
|
|
let html = render("```rust\nlet x = 1;\n```\n");
|
|
assert!(html.contains("class=\"language-rust\""));
|
|
assert!(html.contains("let x = 1;"));
|
|
}
|
|
|
|
#[test]
|
|
fn renders_lists_and_quotes() {
|
|
let html = render("- one\n- two\n\n> quoted\n");
|
|
assert!(html.contains("<ul>"));
|
|
assert!(html.contains("<li>one</li>"));
|
|
assert!(html.contains("<blockquote>"));
|
|
}
|
|
|
|
#[test]
|
|
fn plain_text_drops_the_markup() {
|
|
let text = to_plain_text("# Title\n\nSee [[sgp4|SGP4]] and `code`.\n");
|
|
assert!(text.contains("Title"));
|
|
assert!(text.contains("SGP4"));
|
|
assert!(!text.contains("[["));
|
|
assert!(!text.contains('`'));
|
|
}
|
|
}
|