O aplikaci

'lt-ssg' je generátor statických stránek napsaný v jazyce Rust, který umožňuje uživateli snadno převést soubory formátu markdown do souborů html s tím, že je schopen přidat zvýraznění syntaxe vybraných programovacích jazyků v tzv. fenced blocích a prekompilovat KaTeX (knihovna umožňující věrné zobrazení matematických formulí ve stylu LaTeXu (https://en.wikipedia.org/wiki/LaTeX)), který je obyčejně závislý na JavaScriptu.

Webová stránka aplikace: https://ssg.less-than.net

Github repozitář: zde

Vývojářská dokumentace: zde

Instalace

Vývoj

Funkce jednotlivých modulů jsou shrnuty ve vývojářské dokumentaci ve složce ./docs/. Zde jen malý přehled (mod.rs soubory se vztahují vždy k modulu s názvem nadřazené složky).

|   cli.rs - parsování argumentů příkazové řádky
|   config_handler.rs - správa globální konfigurace
|   debug_print.rs - pomocný modul na printing s --verbose argumentem
|   main.rs - inicializace globální konfigurace a spuštění jednoho z 'commands'
|
+---commands
|   |   mod.rs - jen reexport 'build' a 'init'
|   |
|   +---build
|   |       base_template.rs - definuje vestavěnou základní šablonu pro stavbu html
|   |       mod.rs - spojuje processing markdownu s šablonami
|   |
|   \---init
|           consts.rs - základní konfiguace k importu
|           mod.rs - vytvoří minimální projekt generátoru 
|           user_prompts.rs - pomocné funkce pro ↑
|
+---content_processor
|       katex.rs - jednoduchý wrapper kolem knihovny katex-rs
|       mod.rs - rozděluje soubory na toml záhlaví a markdown + reexport ↓
|       process_md.rs - zpracování markdownu
|       process_toml.rs - zpracování toml
|
\---git_handler
        mod.rs

Návod na použití

CLI

Aplikace se spouští z příkazové řádky s podpříkazem build/help/init. Argumenty, které jsou vidět zde na obrázku je nutné napsat před podpříkaz, jelikož podpříkazy mají parametry vlastní (například na specifikaci výstupní složky).

imagee

Příkaz init pro vás připraví vše potřebné k započetí tvorby nové stránky a build vám ji pak zkompiluje.

Složková struktura stránky

|   config.toml - hlavní konfigurace + globální uživatelské proměnné
|
+---assets - soubory odsud budou nakopírovány do výstupní složky a nezměněny
+---content - markdown a toml soubory budou prohnány šablonovým enginem
|       index.md
|
+---out - výchozí výstupní složka
|       index.html
|
\---templates - složka s šablonami (viz https://tera.netlify.app/docs)
        test.html

Vestavěná výchozí šablona

Pokud není v markdown souboru specifikována proměnná template, je aplikována tato šablona. Obsahuje nejzákladnější součásti html kódu potřebné k funkci aplikace, vše však lze předefinovat díky dědičnosti šablon (viz složka /example v kořenu adresáře aplikace)

<!DOCTYPE html>
<html lang=" {%- block lang -%} en {%- endblock lang -%} ">
<head>
    <meta charset="UTF-8">
    {% block head %}
    {% endblock head %}
    {%- if Config.compile_katex -%}
    {% block katex %}
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.15.3/dist/katex.min.css" integrity="sha384-KiWOvVjnN8qwAZbuQyWDIbfCLFhLXNETzBQjA/92pIowpC0d2O3nppDGQVgwd2nB" crossorigin="anonymous">
    {% endblock katex %}
    {%- endif -%}
</head>
<body>
    {% block body %}
    {{ Content | safe}}
    {% endblock body %}
</body>
</html>

Každá šablona má přístup k proměnným z globálního konfiguračního souboru, ze svého záhlaví (označeno +++ a zakončeno +++ - Pozor záhlaví je povinné v každém markdown souboru) a k proměnné Content -- zkompilovanému markdown obsahu do html.

Známé nedostatky

Použité knihovny

Knihovny je vždy možné najít spolu s odkazy na zdrojové kódy a dokumentaci na
https://lib.rs/crates/<název knihovny> nebo na
https://crates.io/crates/<název knihovny>, jsou také vypsané v Cargo.toml