Break up the walls of text on non-home pages

[oubiwann]

TailwindCSS has some nice content separators, callouts, etc., than can be used on the following pages to break up the text and make the read experience a little better:

• https://lfe.io/learn/
• https://lfe.io/use/

Resources:

• https://www.preline.co/docs/index.html
• https://www.preline.co/examples.html

[oubiwann]

These have potential (both for design and re-thinking info architecture):

• https://www.preline.co/examples/html/scrollspy-sticky-sidebar.html#first
• https://www.preline.co/examples/faq-sections.html#faq-right-aligned-with-border-bottom
• https://www.preline.co/examples/icon-sections.html#medium-size-description-with-icon-blocks
• https://www.preline.co/examples/features-general.html#fg-container-size-image-with-icon-blocks

[oubiwann]

Hrm. This is going to be tricky:

• In order to format our section data in templates that use the above-linked preline examples, we need more control over in-page, heading-level data
• Zola (and Hugo, for that matter) don't seem to have an abstraction for content finer-grained than page
• There doesn't seem to be a way to iterate through headings (in a page)
• There doesn't seem to be a way to iterate through the content under headings (in a page)

There is a Rust markdown library that has an alpha version capable of parsing markdown to an AST:

• https://docs.rs/markdown/1.0.0-alpha.16/markdown/fn.to_mdast.html

Perhaps it would be possible to override the Zola parser? Get the mdast as a Rust data structure, walk the AST, convert each heading and its content to HTML, put those in Tera variables and make the available to Zola templates?

Yikes, that sounds like a doozy of a project.

[oubiwann]

Gonna stop poking now, but should be possible to (with a Zola fork):

• update the Page struct in components/content/src/page.rs to include a new field like ast
• parse the raw content using the Rust markdown parser and converting to mdast instead of HTML
• walk the children of markdown::mdast::Root and generate a new data structure that uses headings + depth
• make this data structure available to Zola/Tera templates off the Page data

[oubiwann]

I've done a little cleanup of the /learn page that should help us limp along until a better/cleaner solution is ready.

[oubiwann]

Moving the longer-term solution for this to the backlog ...

[oubiwann]

Let's see where the work here goes:

• poise redesign lfex/poise#8

If that pans out, we can switch the LFE site to using poise instead of zola, and we can update the templates to use the markdown AST to do the specialised rendering setups to avoid walls of text from straight markdown ...

[oubiwann]

Working on a tool that the poise static generator will need in order for all of this to be possible (extracting selective chunks of a parsed Markdown file for rendering in specific locations in a page template).

That tool is here, and I'm making good progress on it :-D

• https://github.com/oxur/mdsplode

The usage examples in the README are all currently working (v0.1.0, unreleased). I think this tool will be most useful when shell support has landed, which will allow poise to run it in a supervisor and write commands to its stdin to generate the desired output (thus avoiding the bad pattern of shelling out to the system for every markdown file that needs to be processed).