/ Site 模式 / 组合 Steps

核心库提供了一系列基础 step,可以借助 MoonBit 的管道操作符 |> 将它们自由拼接成一条完整的处理管线。本节介绍常用 step 的分类与用法,以及贯穿整条管线的模板变量机制。

pub fn separate_frontmatter(item : Item[String]) -> Item[(Map[String, String], String)]

pub fn[T : Show] extract_markdown(item : Item[T]) -> Item[(Map[String, String], String)]

pub fn[T : Show] parse_markdown(item : Item[T]) -> Item[Array[@markdown.Block]]

separate_frontmatter 将文本拆分为 YAML 元数据(Map[String, String])与正文文本,输入要求是 Item[String];extract_markdown 的作用与之相同,区别在于它接受任意实现了 Show 的类型作为输入,而不局限于 String。parse_markdown 将文本解析为 Markdown 语法树。

pub fn[T : Show] render_markdown(item : Item[T]) -> Item[String]

pub fn[T : Show] render_markdown_and_frontmatter(item : Item[T]) -> Item[String]

pub fn render_markdown_from_ast(item : Item[Array[@markdown.Block]]) -> Item[String]

pub fn render_markdown_and_frontmatter_from_ast(
  item : Item[Array[@markdown.Block]],
  frontmatter : Map[String, String],
) -> Item[String]

render_markdown 直接将文本解析并渲染为 HTML,不处理元数据,如果输入本身带有元数据块,元数据会被当作正文的一部分一并渲染,通常不是想要的效果。render_markdown_and_frontmatter 在渲染前先调用 separate_frontmatter 分离元数据,避免这个问题。render_markdown_from_ast、render_markdown_and_frontmatter_from_ast 是以上两者基于已经解析好的语法树的对应版本,适用于在解析和渲染之间插入了自定义处理逻辑(如转换器)的场景,其中 render_markdown_and_frontmatter_from_ast 需要额外显式传入元数据,因为语法树本身不携带元数据信息。

pub fn[T : Show] add_excerpt(
  item : Item[T],
  separator? : String, // 默认为 "<!--more-->"
  max_length? : Int32, // 默认为 200
  var_name? : String,  // 默认为 "excerpt"
) -> Item[T]

pub fn[T : Show] add_reading_time(
  item : Item[T],
  words_per_minute? : Int32, // 默认为 300
  words_var? : String,       // 默认为 "word_count"
  time_var? : String,        // 默认为 "reading_time"
) -> Item[T]

add_excerpt 会查找 separator 分隔符或按最大字数提取纯文本摘要,并将结果写入模板变量 var_name(默认 $excerpt$);add_reading_time 统计中英文混合词数并按每分钟阅读速度估算阅读分钟数,分别写入 $word_count$ 与 $reading_time$ 模板变量。

pub fn inject_canonical(item : Item[Html], url : String) -> Item[Html]

pub fn inject_open_graph(item : Item[Html], options : OpenGraphOptions) -> Item[Html]

pub fn inject_twitter_card(item : Item[Html], options : TwitterCardOptions) -> Item[Html]

pub fn inject_feed_discovery(
  item : Item[Html],
  feed_url : String,
  title? : String,
  mime_type? : String,
) -> Item[Html]

pub fn inject_sitemap_discovery(item : Item[Html], sitemap_url : String) -> Item[Html]

这些 step 用于向页面 <head> 注入标准 SEO 标签,包括规范链接(Canonical URL)、Open Graph 社交元数据、Twitter Card 标签,以及 RSS/Atom Feed 与 Sitemap 的自动发现声明。

pub fn generate_pagination(
  items : Array[PaginatedItem],
  page_size? : Int32,          // 默认为 10
  base_path? : String,         // 默认为 "posts"
  template_path~ : String,
) -> Thing raise

generate_pagination 将传入的 PaginatedItem 列表按 page_size 切分为多个分页(如 posts/index.html、posts/page/2/index.html 等),并在每个分页中注入 items、current_page、total_pages、prev_url、next_url 等模板变量。

pub fn apply_template(item : Item[String], template : Array[@template.TemplateNode]) -> Item[String]

pub fn apply_template_strict(item : Item[String], template : Array[@template.TemplateNode]) -> Item[String] raise

pub fn load_and_apply_template(item : Item[String], path : String, strict? : Bool) -> Item[String] raise

pub fn use_css(item : Item[String], code : Array[String]) -> Item[String]

pub fn use_js(item : Item[String], code : Array[String]) -> Item[String]

pub fn import_css(item : Item[String], paths : Array[String]) -> Item[String]

pub fn import_js(item : Item[String], paths : Array[String]) -> Item[String]

pub fn inject_head(item : Item[String], html : String) -> Item[String]

pub fn inject_body(item : Item[String], html : String) -> Item[String]

apply_template 是宽松模式的渲染,遇到问题会跳过对应节点、以空内容代替;apply_template_strict 是严格模式,遇到问题会直接 raise 具体的错误,两者都要求预先解析好的模板节点数组。load_and_apply_template 把“读取模板文件、解析、渲染”三步合成一步,strict 参数决定内部走哪种渲染模式,默认宽松。

use_css、use_js 接受的是代码本体,数组中的每一项会各自生成一个独立的 <style>、<script> 标签直接内联到页面中,use_css 注入在 </head> 之前,use_js 注入在 </body> 之前。import_css、import_js 接受的是路径或 URL,以 <link>、<script src> 的形式引用外部资源,不内联代码本体。inject_head、inject_body 接受一段原始 HTML 片段,分别注入到页面的头部、尾部。这几个 step 的注入内容最终都是通过写入 Item.vars 中的对应变量实现的,只有在 item 之后被套用了模板,这些注入内容才会真正体现在渲染输出中。

pub fn[T] set_extension(item : Item[T], extension : String) -> Item[T]

pub fn[T : Thingable] unify(item : Item[T]) -> Item[Thing]

set_extension 修改 item 的目标扩展名,传入的字符串需要带上前导点号,如 .html 而非 html。unify 把最终数据归一为 Thing,是管线中最常见的收尾步骤,要求数据类型实现 Thingable:

pub trait Thingable {
  fn to_thing(Self) -> Thing
}

pub impl Thingable for String
pub impl Thingable for Bytes
pub impl Thingable for Json

String 会被转换为 Thing::Doc,Bytes 会被转换为 Thing::Asset,Json 会被转换为其自身对应的表示,具体的 Thing 定义与写入方式请阅读 输出格式。

pub async fn run_markdown_preprocessors(
  config : @config.BookConfig,
  data : String,
) -> String raise

pub async fn run_markdown_transformers(
  config : @config.BookConfig,
  data : Array[@markdown.Block],
) -> Array[@markdown.Block] raise

run_markdown_preprocessors 对原始文本依次执行一系列外部预处理命令,run_markdown_transformers 对已解析的语法树依次执行一系列外部转换命令。这两个函数本身不是 (Item[T]) -> Item[R] 形状的 step,而是接受、返回裸数据(String、Array[@markdown.Block])的普通函数,接入管线时通常需要配合 Item::map_with_eff 使用:

item.map_with_eff(text => @bridge.run_markdown_preprocessors(config, text))

完整的通信协议、错误类型定义,请阅读 外部插件协议。

除了通过外部命令扩展处理逻辑,Site 模式还允许直接传入一组 MoonBit 函数作为处理步骤:

pub fn use_preprocessor(
  item : Item[String],
  preprocessors : Array[(Item[String]) -> Item[String] raise],
) -> Item[String] raise

pub fn use_transformer(
  item : Item[Array[@markdown.Block]],
  transformers : Array[(Item[Array[@markdown.Block]]) -> Item[Array[@markdown.Block]] raise],
) -> Item[Array[@markdown.Block]] raise

这两个 step 会按顺序依次调用数组中的每一个函数,前一个的输出作为后一个的输入,语义上与外部命令版本的预处理器、转换器完全一致,区别只是执行环境从独立进程变成了进程内的普通函数调用,因此不需要经过 JSON 序列化,性能开销更低,也更方便调试,可以直接打断点、直接抛出 MoonBit 原生的错误类型。

在 Site 模式中模板渲染的上下文变量通过 Item::add_vars、Item::set_var,或者其他 step 内部隐式设置。举例来说,apply_template、apply_template_strict 会隐式地设置变量 body,值为 MarkDown 内容转换为 HTML 的结果,在模板用于显示文章主体。

如果希望像 Book 模式那样,自动把元数据的字段暴露为模板变量,可以使用 render_markdown_and_frontmatter、 render_markdown_and_frontmatter_from_ast step 或:

raw
|> @core.separate_frontmatter
|> x => {
  let (frontmatter, body) = x.data
  x.map(_ => body).add_vars(frontmatter.map(k, v => (k, @template.Value::String(v))))
}

反过来,如果场景不需要元数据出现在模板变量中,完全可以跳过这一步,vars 就不会包含任何元数据内容——这一切都在自己的掌控之中,Book 模式的自动行为只是这套机制的一种预设组合方式,而非唯一的固定行为。

如果需要在 Site 模式中读取外部的结构化数据(如作者信息、站点配置、菜单列表等),可以使用 @data.load_data Step 将指定目录下的 .json 与 .toml 数据加载为全局变量 $data.*$:

raw
|> @data.load_data("data")
|> @core.separate_frontmatter
// 接下来进行 Markdown 解析与模板渲染,模板中即可通过 $data.authors$ 等访问对应数据

Book 模式的 MarkDown 页面渲染函数 process_markdown_page 就是最好的参考示例:

  let t_render_0 = @async.now()
  let rendered_html = @core.render_markdown_and_frontmatter_from_ast(
    seprated.map(_ => ast),
    seprated.data.0,
  )
  @core.record_step_trace("render_markdown", @async.now() - t_render_0)
  let t_tpl_0 = @async.now()
  let item_with_vars = rendered_html
    |> @core.set_extension(".html")
    |> x => {
      let (prev, next) = summary.prev_next(x.location())
      let data_val = @data.load_data_dir_cached(config.extensions.data_dir)
      let fm_vars = seprated.data.0.map((_, v) => v |> @template.String)
      x
      .set_var("data", data_val)
      .add_vars(
        Map([
          (
            "section",
            summary.flatten(x.location(), config.base_url)
            |> @template.Value::from_json,
          ),
          ("site_title", config.title |> String),
          ("site_description", config.description |> String),
          ("site_keywords", config.keywords |> String),
          ("site_authors", config.authors.join(",") |> String),
          ("site_language", config.language |> String),
          (
            "site_languages",
            @template.Value::Array(
              config.languages.map(l => @template.Value::String(l)),
            ),
          ),
          (
            "is_en",
            @template.Value::Bool(
              x.location().replace_all(old="\\", new="/").has_prefix("/en/") ||
              x.location().replace_all(old="\\", new="/").has_prefix("en/"),
            ),
          ),
          (
            "target_lang_url",
            {
              let normalized = x.location().replace_all(old="\\", new="/")
              let clean = if normalized.has_prefix("/") {
                Show::to_string(normalized[1:])
              } else {
                normalized
              }
              let target = if clean.has_prefix("en/") {
                let stripped = Show::to_string(clean[3:])
                if stripped.is_empty() || stripped == "index.html" {
                  "/index.html"
                } else {
                  "/" + stripped
                }
              } else if clean.is_empty() || clean == "index.html" {
                "/en/index.html"
              } else {
                "/en/" + clean
              }
              String(target)
            },
          ),
          ("favicon", config.favicon |> String),
          ("logo", config.logo |> String),
          ("repository", config.repository.unwrap_or("") |> String),
          ("src", config.src |> String),
          ("dest", config.dest |> String),
          ("base_url", config.base_url |> String),
          ("build_time", build_time |> String),
          ("version", version |> String),
          ("breadcrumb", summary.breadcrumb(x.location()) |> String),
          ("current", x.location() |> String),
          (
            "prev",
            prev
            .map(prev => {
              @template.Object(
                Map([
                  ("title", prev.0 |> String),
                  ("location", prev.1 |> String),
                ]),
              )
            })
            .unwrap_or(String("")),
          ),
          (
            "next",
            next
            .map(next => {
              @template.Object(
                Map([
                  ("title", next.0 |> String),
                  ("location", next.1 |> String),
                ]),
              )
            })
            .unwrap_or(String("")),
          ),
        ]),
      )
      .add_vars(fm_vars)
    }
  let templated = item_with_vars
    |> @core.load_and_apply_template(config.extensions.template)
  @core.record_step_trace("apply_template", @async.now() - t_tpl_0)
  let with_seo = templated
    |> x => {
      let mut page = x
      let loc = x.location().replace_all(old="\\", new="/")
      let url_path = if loc.has_prefix("/") { loc } else { "/" + loc }
      let full_page_url = config.site_url.map(base => {
        let b = if base.has_suffix("/") {
          Show::to_string(base[0:base.length() - 1])
        } else {
          base
        }
        b + url_path
      })
      let fm = seprated.data.0
      // 1. Canonical URL
      match full_page_url {
        Some(u) => page = page |> @core.inject_canonical(u)
        None => ()
      }
      // Alternate language hreflang links
      if !config.languages.is_empty() && config.site_url is Some(site_url) {
        let b = if site_url.has_suffix("/") {
          Show::to_string(site_url[0:site_url.length() - 1])
        } else {
          site_url
        }
        let alternates : Array[(String, String)] = []
        for lang in config.languages {
          let alt_url = if lang == config.language {
            b + url_path
          } else {
            b + "/" + lang + url_path
          }
          alternates.push((lang, alt_url))
        }
        page = page |> @core.inject_alternate_languages(alternates)
      }
      // 2. Open Graph
      let page_title = fm.get("title").unwrap_or(config.title)
      let page_desc = match fm.get("description") {
        Some(d) => Some(d)
        None =>
          if config.description != "" {
            Some(config.description)
          } else {
            None
          }
      }
      let page_image = match fm.get("image") {
        Some(img) => Some(img)
        None =>
          if config.logo != "" {
            Some(config.logo)
          } else if config.favicon != "" {
            Some(config.favicon)
          } else {
            None
          }
      }
      let og_enabled = config.features.open_graph_enabled &&
        fm.get("open_graph") != Some("false")
      if og_enabled {
        page = page
          |> @core.inject_open_graph({
            title: Some(page_title),
            description: page_desc,
            url: full_page_url,
            image: page_image,
            site_name: Some(config.title),
            og_type: Some("article"),
            locale: Some(config.language),
          })
      }
      // 3. Twitter Card
      let twitter_enabled = config.features.twitter_card_enabled &&
        fm.get("twitter_card") != Some("false")
      if twitter_enabled {
        let card_type = match fm.get("twitter_card") {
          Some("summary_large_image") => "summary_large_image"
          _ => "summary"
        }
        page = page
          |> @core.inject_twitter_card({
            card: Some(card_type),
            title: Some(page_title),
            description: page_desc,
            image: page_image,
            creator: None,
          })
      }
      // 4. Feed & Sitemap discovery
      if config.feed_enabled && config.site_url is Some(site_url) {
        let feed_href = if site_url.has_suffix("/") {
          site_url + "feed.xml"
        } else {
          site_url + "/feed.xml"
        }
        page = page
          |> @core.inject_feed_discovery(feed_href, title=config.title)
      }
      if config.sitemap_enabled {
        let sitemap_url = match config.site_url {
          Some(s) =>
            if s.has_suffix("/") {
              s + "sitemap.xml"
            } else {
              s + "/sitemap.xml"
            }
          None =>
            if config.base_url.has_suffix("/") {
              config.base_url + "sitemap.xml"
            } else {
              config.base_url + "/sitemap.xml"
            }
        }
        page = page |> @core.inject_sitemap_discovery(sitemap_url)
      }
      page
    }
  let t_assets_0 = @async.now()
  let final_item = with_seo
    |> @core.import_css(config.extensions.import_css)
    |> @core.import_js(config.extensions.import_js)
    |> @core.use_css(config.extensions.use_css)
    |> @core.use_js(config.extensions.use_js)
    |> @core.inject_head(config.extensions.inject_head.join("\n"))
    |> @core.inject_body(config.extensions.inject_body.join("\n"))
    |> @core.unify
  @core.record_step_trace("inject_assets", @async.now() - t_assets_0)