///|
/// A single chapter link in a table of contents.
#derive(Eq, Debug)
pub(all) struct SummaryLink {
title : String
location : String
source : String
/// Nested sub-chapters under this chapter, if any.
nested_items : Array[SummaryItem]
}
///|
pub extend SummaryLink with Eq::{not_equal, equal}
///|
pub extend SummaryLink with @debug.Debug::{to_repr}
///|
/// A single entry in a table of contents.
#derive(Eq, Debug)
pub(all) enum SummaryItem {
/// A link to a chapter.
Link(SummaryLink)
/// A part title, grouping subsequent chapters under a heading.
PartTitle(String)
/// A visual separator between groups of chapters.
Separator
}
///|
pub extend SummaryItem with Eq::{not_equal, equal}
///|
pub extend SummaryItem with @debug.Debug::{to_repr}
///|
#derive(Eq, Debug)
pub(all) struct SummarySectionItem {
item : SummaryItem
numbered : Bool
}
///|
pub extend SummarySectionItem with Eq::{not_equal, equal}
///|
pub extend SummarySectionItem with @debug.Debug::{to_repr}
///|
/// The parsed structure of a book's table of contents (`SUMMARY.md`),
/// split into an optional prefix section, the main numbered chapters, and
/// an optional suffix section — mirroring the conventional structure of
/// an mdBook-style summary file.
#derive(Eq, Debug)
pub(all) struct Summary {
title : String
prefix_chapters : Array[SummaryItem]
numbered_chapters : Array[SummaryItem]
suffix_chapters : Array[SummaryItem]
ordered_items : Array[SummarySectionItem]
}
///|
pub extend Summary with Eq::{not_equal, equal}
///|
pub extend Summary with @debug.Debug::{to_repr}
///|
/// A single article's indexed content, e.g. for building a client-side
/// search index over the site's pages.
#derive(Eq, Debug, ToJson)
pub(all) struct ArticleIndex {
title : String
location : String
content : String
}
///|
pub extend ArticleIndex with Eq::{not_equal, equal}
///|
pub extend ArticleIndex with @debug.Debug::{to_repr}
///|
pub extend ArticleIndex with ToJson::{to_json}
///|
fn flatten_items(
items : Array[SummaryItem],
depth : Int32,
current : String,
base_url : String,
numbered~ : Bool = false,
counter~ : Ref[Int32] = Ref(0),
prefix~ : String = "",
) -> Array[Json] {
let result : Array[Json] = []
let mut local_counter = 0
for item in items {
match item {
Separator => result.push({ "is_separator": Json(true) })
PartTitle(title) => {
counter.val = 0
result.push({ "is_part_title": Json(true), "title": Json(title) })
}
Link(link) => {
let number = if depth == 0 {
counter.val += 1
prefix + counter.val.to_string()
} else {
local_counter += 1
prefix + local_counter.to_string()
}
let location = if base_url.has_suffix("/") {
base_url[0:base_url.length() - 1] + link.location
} else {
base_url + link.location
}
if numbered {
result.push({
"is_link": Json(true),
"title": Json(link.title),
"location": location,
"source": link.source,
"depth": Json(depth),
"is_current": Json(link.location == current),
"number": Json(number),
})
} else {
result.push({
"is_link": Json(true),
"title": Json(link.title),
"location": location,
"source": link.source,
"depth": Json(depth),
"is_current": Json(link.location == current),
})
}
result.append(
flatten_items(
link.nested_items,
depth + 1,
current,
base_url,
numbered~,
prefix=number + ".",
),
)
}
}
}
result
}
///|
fn flatten_ordered_items(
items : Array[SummarySectionItem],
current : String,
base_url : String,
) -> Array[Json] {
let result : Array[Json] = []
let counter : Ref[Int32] = Ref(0)
for sec in items {
match sec.item {
Separator => result.push({ "is_separator": Json(true) })
PartTitle(title) => {
counter.val = 0
result.push({ "is_part_title": Json(true), "title": Json(title) })
}
Link(link) => {
let number = if sec.numbered {
counter.val += 1
counter.val.to_string()
} else {
""
}
let location = if base_url.has_suffix("/") {
base_url[0:base_url.length() - 1] + link.location
} else {
base_url + link.location
}
if sec.numbered {
result.push({
"is_link": Json(true),
"title": Json(link.title),
"location": location,
"source": link.source,
"depth": Json(0),
"is_current": Json(link.location == current),
"number": Json(number),
})
} else {
result.push({
"is_link": Json(true),
"title": Json(link.title),
"location": location,
"source": link.source,
"depth": Json(0),
"is_current": Json(link.location == current),
})
}
if link.nested_items.length() > 0 {
result.append(
flatten_items(
link.nested_items,
1,
current,
base_url,
numbered=sec.numbered,
prefix=if sec.numbered { number + "." } else { "" },
),
)
}
}
}
}
result
}
///|
/// Returns a JSON representation of this summary, rooted at `location`,
/// e.g. for use as a template variable describing the current section's
/// navigation structure.
pub fn Summary::flatten(
self : Summary,
current : String,
base_url : String,
) -> Json {
let current = unify_url(current)
let prefix_flat = flatten_items(self.prefix_chapters, 0, current, base_url)
let numbered_flat = flatten_items(
self.numbered_chapters,
0,
current,
base_url,
numbered=true,
)
let suffix_flat = flatten_items(self.suffix_chapters, 0, current, base_url)
let chapters_flat = if self.ordered_items.length() > 0 {
flatten_ordered_items(self.ordered_items, current, base_url)
} else {
let flat : Array[Json] = []
flat.append(prefix_flat)
flat.append(numbered_flat)
flat.append(suffix_flat)
flat
}
{
"title": Json(self.title),
"chapters": Json::array(chapters_flat),
"prefix_chapters": Json::array(prefix_flat),
"numbered_chapters": Json::array(numbered_flat),
"suffix_chapters": Json::array(suffix_flat),
}
}
///|
fn parse_summary_item(item : Array[@markdown.Block]) -> SummaryItem? {
let link : SummaryLink? = extract_item_link(item)
let nested : Array[SummaryItem] = extract_nested_items(item)
link.map(link => {
Link({
title: link.title,
location: link.location,
source: link.source,
nested_items: nested,
})
})
}
///|
fn extract_item_link(item : Array[@markdown.Block]) -> SummaryLink? {
match item {
[Paragraph(inlines), ..] =>
match inlines {
[Link(title, url), ..] =>
Some({
title: @markdown.Plainable::to_plain(title),
location: unify_url(url),
source: url,
nested_items: [],
})
_ => None
}
_ => None
}
}
///|
fn extract_nested_items(item : Array[@markdown.Block]) -> Array[SummaryItem] {
for block in item {
match block {
List(lb) => return parse_list_items(lb.items)
_ => continue
}
} nobreak {
[]
}
}
///|
fn parse_list_items(
items : Array[Array[@markdown.Block]],
) -> Array[SummaryItem] {
let result : Array[SummaryItem] = []
for item in items {
match parse_summary_item(item) {
Some(si) => result.push(si)
None => continue
}
}
result
}
///|
/// Parses a book's `SUMMARY.md` (already parsed into a Markdown AST) into
/// its structured `Summary` representation.
pub fn parse_summary(doc : @markdown.Markdown) -> Summary {
let title : String = find_title(doc)
let prefix_chapters : Array[SummaryItem] = []
let numbered_chapters : Array[SummaryItem] = []
let suffix_chapters : Array[SummaryItem] = []
let ordered_items : Array[SummarySectionItem] = []
let blocks = skip_title(doc)
let mut phase = 0 // 0=prefix, 1=numbered, 2=suffix
let pending_headings : Array[String] = []
fn target() -> Array[SummaryItem] {
if phase == 0 {
prefix_chapters
} else if phase == 1 {
numbered_chapters
} else {
suffix_chapters
}
}
fn flush_headings() -> Unit {
for h in pending_headings {
target().push(PartTitle(h))
ordered_items.push({ item: PartTitle(h), numbered: false, })
}
pending_headings.clear()
}
for block in blocks {
match block {
Heading(_, inlines) =>
pending_headings.push(@markdown.Plainable::to_plain(inlines))
ThematicBreak => {
flush_headings()
target().push(Separator)
ordered_items.push({ item: Separator, numbered: false, })
}
List(lb) => {
if phase == 0 {
phase = 1
}
flush_headings()
for item in parse_list_items(lb.items) {
numbered_chapters.push(item)
ordered_items.push({ item, numbered: true, })
}
}
Paragraph(inlines) => {
flush_headings()
if phase == 1 {
phase = 2
}
for item in extract_root_link_items(inlines) {
target().push(item)
ordered_items.push({ item, numbered: false, })
}
}
_ => ()
}
}
{ title, prefix_chapters, numbered_chapters, suffix_chapters, ordered_items, }
}
///|
fn unify_url(url : String) -> String {
let url = url.replace_all(old="\\", new="/")
let path = @path.Path(url)
let basename = Show::to_string(path.basename())
let result = path
.dirname()
.join(
basename
.rev_find(".")
.map(index => Show::to_string(basename[:index]))
.unwrap_or(basename) +
".html",
)
|> Show::to_string
|> s => { s.replace_all(old="\\", new="/") }
if result[0:2] == "./" {
"/" + (result[2:] |> Show::to_string)
} else if result[0:1] == "/" {
result
} else {
"/" + result
}
}
///|
fn find_title(doc : @markdown.Markdown) -> String {
for block in doc {
match block {
Heading(1, inlines) => return @markdown.Plainable::to_plain(inlines)
_ => continue
}
} nobreak {
"Summary"
}
}
///|
fn skip_title(doc : @markdown.Markdown) -> Array[@markdown.Block] {
let mut found = false
let result : Array[@markdown.Block] = []
for block in doc {
if !found {
match block {
Heading(1, _) => {
found = true
continue
}
_ => result.push(block)
}
} else {
result.push(block)
}
}
result
}
///|
fn extract_root_link_items(
inlines : Array[@markdown.Inline],
) -> Array[SummaryItem] {
let result : Array[SummaryItem] = []
for inline in inlines {
match inline {
Link(title, url) =>
result.push(
Link({
title: @markdown.Plainable::to_plain(title),
location: unify_url(url),
source: url,
nested_items: [],
}),
)
_ => continue
}
}
result
}
///|
/// Renders a Markdown string to its plain-text representation (stripping
/// all Markdown/HTML markup), e.g. for use in generating search indexes
/// or previews from summary/article content.
pub fn md_to_plain(input : String) -> String {
let input = input
.replace_all(old="\r\n", new="\n")
.replace_all(old="\r", new="\n")
let out = StringBuilder()
let mut i = 0
while i < input.length() {
let ch = input[i]
if ch == '#' {
while i < input.length() && input[i] == '#' {
i = i + 1
}
while i < input.length() && input[i] == ' ' {
i = i + 1
}
} else if ch == '*' || ch == '_' {
let marker = ch
if i + 1 < input.length() && input[i + 1] == marker {
i = i + 2
} else {
i = i + 1
}
} else if ch == '`' {
i = i + 1
} else if ch == '!' && i + 1 < input.length() && input[i + 1] == '[' {
i = i + 2
while i < input.length() && input[i] != ']' {
i = i + 1
}
i = i + 1
if i < input.length() && input[i] == '(' {
while i < input.length() && input[i] != ')' {
i = i + 1
}
i = i + 1
}
} else if ch == '[' {
i = i + 1
while i < input.length() && input[i] != ']' {
if input[i].to_char() is Some(ch) {
out.write_char(ch)
}
i = i + 1
}
i = i + 1
if i < input.length() && input[i] == '(' {
while i < input.length() && input[i] != ')' {
i = i + 1
}
i = i + 1
}
} else if ch == '<' {
while i < input.length() && input[i] != '>' {
i = i + 1
}
i = i + 1
} else if ch == '>' && (i == 0 || input[i - 1] == '\n') {
i = i + 1
if i < input.length() && input[i] == ' ' {
i = i + 1
}
} else if ch == '|' {
out.write_char(' ')
i = i + 1
} else {
if ch.to_char() is Some(ch) {
out.write_char(ch)
}
i = i + 1
}
}
out
.to_string()
.replace_all(old="\n", new=" ")
.replace_all(old="---", new=" ")
.to_lower()
.trim()
.to_owned()
}
///|
/// Builds a search/content index over all articles reachable from this
/// summary, reading each article's source file from `src`.
///
/// Raises if any referenced article's source file cannot be read.
pub fn Summary::index_articles(
self : Summary,
src : String,
) -> Array[ArticleIndex] raise {
let articles : Array[ArticleIndex] = []
fn collect(items : Array[SummaryItem]) -> Unit raise {
for item in items {
match item {
SummaryItem::Link(link) => {
let path = @path.Path(src).join(link.source) |> Show::to_string
articles.push({
title: link.title,
location: link.location,
content: path |> @fs.read_file_to_string |> md_to_plain,
})
collect(link.nested_items)
}
_ => ()
}
}
}
collect(
[..self.prefix_chapters, ..self.numbered_chapters, ..self.suffix_chapters],
)
articles
}
///|
/// Returns a breadcrumb string describing the path from the root of the
/// table of contents down to the chapter located at `location`.
pub fn Summary::breadcrumb(self : Summary, current : String) -> String {
let current = unify_url(current)
fn find(items : Array[SummaryItem], path : Array[String]) -> Array[String]? {
for item in items {
match item {
SummaryItem::Link(link) => {
let new_path = path + [link.title]
if link.location == current {
return Some(new_path)
}
match find(link.nested_items, new_path) {
Some(p) => return Some(p)
None => ()
}
}
_ => ()
}
}
None
}
let path = match find(self.prefix_chapters, []) {
Some(p) => p
None =>
match find(self.numbered_chapters, []) {
Some(p) => p
None =>
match find(self.suffix_chapters, []) {
Some(p) => p
None => return "/ ???"
}
}
}
"/ " + path.join(" / ")
}
///|
/// Returns the previous and next chapter (as `(title, location)` pairs),
/// relative to the chapter located at `location`, according to this
/// summary's chapter ordering. Either value is `None` if there is no
/// previous/next chapter (e.g. at the start or end of the book).
pub fn Summary::prev_next(
self : Summary,
current : String,
) -> ((String, String)?, (String, String)?) {
let current = unify_url(current)
let flat : Array[SummaryLink] = []
fn collect(items : Array[SummaryItem]) -> Unit {
for item in items {
match item {
SummaryItem::Link(link) => {
flat.push(link)
collect(link.nested_items)
}
_ => ()
}
}
}
collect(self.prefix_chapters)
collect(self.numbered_chapters)
collect(self.suffix_chapters)
fn to_val(link : SummaryLink) -> (String, String) {
(link.title, link.location)
}
match flat.search_by(link => link.location == current) {
None => (None, None)
Some(i) =>
(
if i > 0 {
Some(to_val(flat[i - 1]))
} else {
None
},
if i < flat.length() - 1 {
Some(to_val(flat[i + 1]))
} else {
None
},
)
}
}
// @block page-meta
///|
/// Per-page metadata collected from a `Summary` plus each source file's
/// frontmatter, used for feed and sitemap generation.
///
/// Every frontmatter field is optional: missing values are either omitted
/// from the generated output or fall back to site-level config. The
/// recognized fields are `description`, `keywords`, `authors`, `language`
/// and `date`; `title` is taken from the summary link's own title.
#derive(Eq, Debug)
pub(all) struct PageMeta {
title : String
location : String
description : String?
keywords : String?
authors : String?
language : String?
date : String?
}
///|
pub extend PageMeta with Eq::{not_equal, equal}
///|
pub extend PageMeta with @debug.Debug::{to_repr}
// @end
///|
/// Collects per-page metadata for every link reachable from this summary,
/// reading each article's source file under `src` to extract frontmatter
/// fields.
///
/// Raises if any referenced source file cannot be read.
pub fn Summary::collect_page_meta(
self : Summary,
src : String,
) -> Array[PageMeta] raise {
let metas : Array[PageMeta] = []
fn collect(items : Array[SummaryItem]) -> Unit raise {
for item in items {
match item {
SummaryItem::Link(link) => {
let path = @path.Path(src).join(link.source) |> Show::to_string
let raw = @fs.read_file_to_string(path)
let (fm, _) = @core.separate_frontmatter(
@core.Item::new(raw, link.source),
).data
metas.push({
title: link.title,
location: link.location,
description: fm.get("description"),
keywords: fm.get("keywords"),
authors: fm.get("authors"),
language: fm.get("language"),
date: fm.get("date"),
})
collect(link.nested_items)
}
_ => ()
}
}
}
collect(
[..self.prefix_chapters, ..self.numbered_chapters, ..self.suffix_chapters],
)
metas
}
///|
fn xml_escape(s : String) -> String {
let out = StringBuilder()
for ch in s {
match ch {
'&' => out.write_string("&")
'<' => out.write_string("<")
'>' => out.write_string(">")
'"' => out.write_string(""")
'\'' => out.write_string("'")
_ => out.write_char(ch)
}
}
out.to_string()
}
///|
fn pad_2(s : String) -> String {
if s.length() == 0 {
"00"
} else if s.length() == 1 {
"0" + s
} else {
s
}
}
///|
fn pad_4(s : String) -> String {
let len = s.length()
if len >= 4 {
s
} else if len == 3 {
"0" + s
} else if len == 2 {
"00" + s
} else if len == 1 {
"000" + s
} else {
"0000"
}
}
///|
/// Converts a timestamp into RFC 3339 `YYYY-MM-DDTHH:MM:SSZ` structurally.
/// Normalizes separators (`/` or `-`), zero-pads single-digit components
/// (month, day, hours, minutes, seconds), and ensures a valid RFC 3339 timezone.
fn to_rfc3339(build_time : String) -> String {
let s = Show::to_string(build_time.trim())
if s.length() == 0 {
return ""
}
let sep_idx = match s.find("T") {
Some(i) => Some(i)
None =>
match s.find("t") {
Some(i) => Some(i)
None => s.find(" ")
}
}
let (date_part, time_and_tz) = match sep_idx {
Some(i) => (Show::to_string(s[:i]), Show::to_string(s[i + 1:].trim()))
None => (s, "")
}
let norm_date = date_part.replace_all(old="/", new="-")
let date_components = norm_date
.split("-")
.map(p => Show::to_string(p.trim()))
.to_array()
if date_components.length() < 3 {
return s.replace_all(old="/", new="-").replace_all(old=" ", new="T") +
(if s.has_suffix("Z") { "" } else { "Z" })
}
let year = pad_4(date_components[0])
let month = pad_2(date_components[1])
let day = pad_2(date_components[2])
let formatted_date = "\{year}-\{month}-\{day}"
if time_and_tz.length() == 0 {
return "\{formatted_date}T00:00:00Z"
}
let (time_part, tz_part) = if time_and_tz.has_suffix("Z") ||
time_and_tz.has_suffix("z") {
(Show::to_string(time_and_tz[:time_and_tz.length() - 1]), "Z")
} else {
match time_and_tz.find("+") {
Some(plus_idx) =>
(
Show::to_string(time_and_tz[:plus_idx]),
Show::to_string(time_and_tz[plus_idx:]),
)
None =>
match time_and_tz.rev_find("-") {
Some(minus_idx) =>
if minus_idx > 0 {
(
Show::to_string(time_and_tz[:minus_idx]),
Show::to_string(time_and_tz[minus_idx:]),
)
} else {
(time_and_tz, "Z")
}
None => (time_and_tz, "Z")
}
}
}
let time_components = time_part
.split(":")
.map(p => Show::to_string(p.trim()))
.to_array()
let hour = if time_components.length() > 0 {
pad_2(time_components[0])
} else {
"00"
}
let minute = if time_components.length() > 1 {
pad_2(time_components[1])
} else {
"00"
}
let second = if time_components.length() > 2 {
let sec_str = time_components[2]
match sec_str.find(".") {
Some(dot_idx) => {
let sec_int = Show::to_string(sec_str[:dot_idx])
let sec_frac = Show::to_string(sec_str[dot_idx:])
pad_2(sec_int) + sec_frac
}
None => pad_2(sec_str)
}
} else {
"00"
}
let formatted_time = "\{hour}:\{minute}:\{second}"
"\{formatted_date}T\{formatted_time}\{tz_part}"
}
///|
/// Renders an Atom feed for the given pages.
///
/// Returns an empty string when `config.site_url` is unset, since Atom
/// requires absolute entry URLs and the site has no way to construct them.
///
/// `build_time` (a `YYYY/MM/DD HH:MM:SS` string) is used as the feed-level
/// `` timestamp and as the fallback for entries whose source file
/// has no `date` frontmatter field.
pub fn generate_feed_xml(
config : @config.BookConfig,
metas : Array[PageMeta],
build_time : String,
) -> String {
guard config.site_url is Some(site_url) else { "" }
let ts = to_rfc3339(build_time)
let author = if config.authors.length() > 0 { config.authors[0] } else { "" }
let out = StringBuilder()
out.write_string("\n")
out.write_string("\n")
out.write_string(" \{xml_escape(config.title)}\n")
out.write_string(" \{xml_escape(site_url)}\n")
out.write_string(" \n")
out.write_string(" \{ts}\n")
if author != "" {
out.write_string(" \{xml_escape(author)}\n")
}
let limit = if config.feed_limit > metas.length() {
metas.length()
} else {
config.feed_limit
}
for i = 0; i < limit; i = i + 1 {
let m = metas[i]
let url = site_url + m.location
out.write_string(" out.write_string(" xml:lang=\"\{xml_escape(lang)}\"")
None => ()
}
out.write_string(">\n")
out.write_string(" \{xml_escape(m.title)}\n")
out.write_string(" \{xml_escape(url)}\n")
out.write_string(" \n")
out.write_string(" \{m.date.unwrap_or(ts)}\n")
let entry_authors : Array[String] = match m.authors {
Some(a) => a.split(",").map(s => s.trim().to_owned()).to_array()
None => config.authors
}
for a in entry_authors {
if a != "" {
out.write_string(" \{xml_escape(a)}\n")
}
}
match m.description {
Some(d) => out.write_string(" \{xml_escape(d)}\n")
None => ()
}
match m.keywords {
Some(k) =>
for kw in k.split(",") {
let t = kw.trim().to_owned()
if t != "" {
out.write_string(" \n")
}
}
None => ()
}
out.write_string(" \n")
}
out.write_string("\n")
out.to_string()
}
///|
/// Renders a sitemap for the given pages, using absolute URLs when
/// `config.site_url` is set and `base_url`-relative URLs otherwise.
pub fn generate_sitemap_xml(
config : @config.BookConfig,
metas : Array[PageMeta],
) -> String {
let out = StringBuilder()
out.write_string("\n")
out.write_string(
"\n",
)
for m in metas {
let url = match config.site_url {
Some(s) => s + m.location
None =>
if config.base_url.has_suffix("/") {
Show::to_string(config.base_url[0:config.base_url.length() - 1]) +
m.location
} else {
config.base_url + m.location
}
}
out.write_string(" \n")
out.write_string(" \{xml_escape(url)}\n")
match m.date {
Some(d) => out.write_string(" \{xml_escape(d)}\n")
None => ()
}
out.write_string(" \n")
}
out.write_string("\n")
out.to_string()
}
///|
/// Renders standard `robots.txt` content, optionally including a reference
/// to the site's `sitemap.xml`.
pub fn generate_robots_txt(
sitemap_url~ : String? = None,
allow~ : Array[String] = ["/"],
disallow~ : Array[String] = [],
) -> String {
let b = StringBuilder()
b.write_string("User-agent: *\n")
for a in allow {
b.write_string("Allow: \{a}\n")
}
for d in disallow {
b.write_string("Disallow: \{d}\n")
}
match sitemap_url {
Some(url) => b.write_string("\nSitemap: \{url}\n")
None => ()
}
b.to_string()
}