module

Utils

Constants

BLOCK_TAGS = Set {"address", "article", "aside", "blockquote", "body", "br", "caption", "center", "colgroup", "dd", "details", "dialog", "div", "dl", "dt", "fieldset", "figcaption", "figure", "footer", "form", "h1", "h2", "h3", "h4", "h5", "h6", "head", "header", "hgroup", "hr", "html", "legend", "li", "main", "menu", "nav", "noscript", "ol", "optgroup", "option", "p", "pre", "search", "section", "summary", "table", "tbody", "td", "textarea", "tfoot", "th", "thead", "title", "tr", "ul"}

Tags whose boundaries separate words. Inline tags (a, em, code, ...) don't: "Nicolino," must read "Nicolino," not "Nicolino ,", which is how Lexbor's inner_text joined them too.

RAW_TEXT_TAGS = Set {"script", "style"}

Elements whose raw text content is never visible

Class methods

content_globs(base_path : Path) : Array(String)

Glob patterns for markdown, html and pandoc content under a base path

create_content_file(sources : Hash(String, String), base : Path, kind : String) : Markdown::File | Nil

Create the right content file for a source based on its extension kind is used in error messages (e.g. "post", "page")

excerpt_from_text(text : String, limit = 200) : String

Truncate already-plain text (see plain_text) at a word boundary

find_all(path, extension)

Find all files with given extension in path, if two files are alternative languages of one another they are grouped together.

lang_suffix(lang : String) : String

Suffix to append to a filename for a given language (empty for the default language, ".#{lang}" otherwise)

language_links_for(output_path : String | Path, lang : String, style : Symbol = :file_suffix) : Array(Hash(String, String))

Alternate-language links for a generated page. Two output conventions exist (issue #54):

:file_suffix (default): "<stem>.<lang>.html" / "<stem>.html", used by post and folder index pages (output/posts/index.es.html)
:dir_suffix: the FIRST directory under output/ carries the language marker (output/tags.es/foo/index.html), used by taxonomies, the archive and galleries roots

Returns one {lang, link, title} hash per other configured language. This is the site-level helper behind translation switcher menus.

output_prefix

The configured output directory with a trailing slash, for building URL prefixes (e.g. "output/", "public/site/")

parallel_chunks(inputs : Array(String), chunk_size : Int32 = 100, &block : Array(String), Int32 -> T) : Array(T) forall T

Process inputs in parallel chunks, returning per-chunk results in order. Errors in a chunk are logged and that chunk is skipped.

path_to_link(path, extension = nil)

Convert path to link, optionally changing extension

path_to_link("output/foo/../bar") # => "/bar"

plain_text(html : String) : String

Plain text of an HTML fragment: block-level tags become spaces (so words on either side of a block boundary stay apart), inline tags vanish, entities are decoded, whitespace is collapsed. Both the reading-time word count and the meta description derive from this, so a page computes it once instead of running two full Lexbor parses of its HTML.

A single pass over the bytes: about 20x faster than parsing with Lexbor and 5x faster than a regex strip, on a typical page. Tag and comment contents are dropped wholesale, quoted attribute values and "-->" included.

should_skip_file?(base_path : Path) : Bool

Filter out files from directories that correspond to disabled features

slugify(string)

text_excerpt(html : String, limit = 200) : String

Plain-text excerpt of an HTML fragment, for meta description tags: at most limit characters, cut at a word boundary with an ellipsis.

titlecase(string)

word_count(html : String) : Int32

Word count of an HTML fragment's text, for reading-time estimates in themes.

words_in(text : String) : Int32

Word count of already-plain text (see plain_text): the words are separated by exactly one space