#lang scribble/manual
@; SPDX-License-Identifier: BlueOak-1.0.0
@; This file is licensed under the Blue Oak Model License 1.0.0.
@(require "scribble-helpers.rkt")
@(require (for-label "../pollen.rkt"
"../dust.rkt"
"../crystalize.rkt"
racket/base
racket/contract
racket/string
txexpr
pollen/pagetree))
@title{@filepath{crystalize.rkt}}
@defmodule["crystalize.rkt" #:packages ()]
“Crystalizing” is an extra layer in between docs and templates that destructures the doc and stores
it in various pieces in a SQLite cache. Individual articles save chunks of rendered HTML to the
cache when their individual pages are rendered. When pulling together listings of articles in
different contexts that need to be filtered and sorted, a SQL query is much faster than trolling
through the Pollen cache for matching docs and regenerating the HTML.
@defproc[(parse-and-cache-article! [pagenode pagenode?] [doc txexpr?]) non-empty-string?]
Returns a string containing the HTML of @racket[_doc]. @margin-note{This is one function that breaks
my convention of using a prefix of @tt{html$-} for functions that return a single string of HTML.}
Privately, it does a lot of other work. The article is analyzed, additional metadata is constructed,
and it is saved to the SQLite cache. If the article specifies a @racket['series] meta, information
about that series is fetched and used in the rendering of the article. If there are @racket[note]s
in the doc, they are parsed and saved individually to the SQLite cache. If any of the notes use the
@code{#:disposition} attribute, information about the disposition is parsed out and used in the
rendering of the article.
