Konverti de Markdaŭno al HTML per emem

Oni ne trovos la respondojn kiujn oni serĉas ĝis oni haltas serĉi ekstere kaj komenciĝas serĉi ilin el oni mem.
—JJ, Ergo Proxy

Enhavotabelo

• Enkonduko
• Instalo
• Uzado
• Finrimarkoj

Enkonduko

Mi ĉiam volis manieron por krei HTML-dokumentojn el miaj markdaŭnaj dosieroj. Komence, mi nur volis havi HTML-dosierojn el miaj tekstaj dosieroj por ke mi povu vidi ilin per la poŝtelefono. Poste, mi deziris havi manieron por krei tiujn dosierojn por ke mi povu alŝuti ilin al la interreto kaj vidi ilin per aliaj aparatoj. Jam ekzistas iloj por ja fari tion. Mi provis ilin, tamen mi trovis min mem ŝanĝi la eligon ofte nur por igi ilin akcepteblaj. Neniuj el ili konformiĝis al mia kriterio: facila por munti, facila por uzi, kaj realigas decan eligon.

Mi skribis emem kiel respondo al tiuj bezonoj. Emem estas eta ilo kiu ricevas markdaŭnajn dosierojn aŭ el la ĉefenigujo aŭ diska dosiero, tiam liveras HTML-eligon kiu estas sufiĉe deca, almenaŭ por kutima rigardado.

Instalo

Haveblas emem per Nix. Se oni ne ankoraŭ havas Nix, oni povas instali ĝin per:

$ curl https://nixos.org/nix/install | bash

Tiam, oni nun povas instali emem per:

$ nix-env -i emem

Se oni ne povas instali Nix, tamen ĝavo estas instalita, oni povas anstataŭ krei porokazan skripton:

$ mkdir ~/bin
$ curl -sSLo ~/bin/emem.jar https://github.com/ebzzry/emem/releases/download/v0.2.50/emem.jar
$ cat > ~/bin/emem << EOF
#!/usr/bin/env bash
java -jar \$HOME/bin/emem.jar \$@
EOF
$ chmod +x ~/bin/emem

Se oni jam finis skribi ĝin, oni povas kontroli la version per:

$ emem --version

La plej ĵusa versio estas 0.2.50.

Uzado

Ĉe la plej baza nivelo, emem simple ruliĝas kontraŭ markdaŭna dosiero, kaj liveras bazan, tamen plenan HTML-dosieron kun ĉiom da necesaj risurcoj por ĝusta paĝvido. Aplikante emem al dosiero nomita LEGUMIN.md:

$ emem LEGUMIN.md

kreas la jenan arbon:

static/
  css/
  ico/
  js/
LEGUMIN.html
LEGUMIN.md

Male, ruli emem kiel jene:

$ emem -s LEGUMIN.md

kreas la jenan arbon:

LEGUMIN.html
LEGUMIN.md

La opcio -s forigas la bezonon por krei apartan risurcan dosieron, kaj metas ĉiom da bezonitaj risurcoj al la eliga dosiero plifaciligante la rigardadon de la eligaj dokumentoj ĉe aparatoj kiel poŝtelefonoj kaj tabuletoj.

Memoru, ke la dokumentotitolo ene la dosiero, estos uzita kiel la baznomo de la dosiero. Do, de LEGUMIN.md, liveras <title>LEGUMIN.md</title> en la HEAD-etikedo. Se oni strukturas la markdaŭnajn dosierojn, en kiu, la unuaj du linioj aspektas jene:

Foo Bar
=======

tiam la unua linio funkcias kiel la dokumentotitolo. Por tiel fari, plenu:

$ emem -F LEGUMIN.md

Tio liveras <title>Foo Bar</title>.

Tio agrablas kaj dandas, sed se oni nur volas krei nur rudimentan dokumenton sen ĉiom da ornamaĵoj, uzu la senornaman reĝimon:

$ emem -Rp LEGUMIN.md

La opcio -R diras al emem por ne krei la risurcajn dosierojn. La opcio -p forigas kaj la CSS-stilojn kaj ĝavoskriptkodon.

Se oni volas ŝanĝi la nomon de la eliga dosiero, uzu la opcion -o.

$ emem -o mia-dosiero.html LEGUMIN.md

Se oni havas markdaŭnajn dosierojn en ~/Desktop/, oni povas krei HTML-dosireoj el ili en unu falplonĝo:

$ emem ~/Desktop

Se oni ne ŝatas la implicitan paĝlarĝecon—40 em—uzu la opcion -f por uzi la maksimuman paĝlarĝecon de la retumilo:

$ emem -f LEGUMIN.md

Kapablo kiu ege plaĉas al mi, estas kunfandado. Ĉi tio ebligas onin por kombini plurajn dosireojn en sola eligo. Ekzemple, se oni havas a.md, b.md, kaj c.md, oni povas kunfandi ilin al index.html per la opcio -m:

$ emem -mo index.html a.md b.md c.md

Se oni planas eldoni por la TTT, estas grave, ke oni havas la valorojn de la priskriba kaj ŝlosila meta-atribuoj. Oni povas fari ĝin per la opcioj -D kaj -K, respektive:

$ emem -D 'Retejo pri omaroj kaj kraboj \
-K 'omaroj, kraboj, blogo, ĵurnalo, retejo, maromanĝoj, monstroj' \
LEGUMIN.md

Ankaŭ eblas specifu «Open Graph Protocol»-valorojn:

$ emem -D Ve -K 'a, b, c' \
--og-title "Kraboj kaj Omaroj" --og-type article \
--og-url "https://retejo.ie/z.html" --og-image "https://retejo.ie/imagesdo.webp" \
LEGUMIN.md

Se oni volas uzi Guglan «Analytics», specifu la naŭ-ciferan kodon, kun la streketo:

$ emem -D Ve -K 'a, b -A 12345678-9 LEGUMIN.md

Se la enhavo de la retejo precipe ne estas en la angla, estas bone por specifi la lingvon, por helpi serĉilojn indeksigi la retejon ĝuste; ankaŭ helpas la programaron, kiel ekranlegiloj, specifi la lingvon por la parolo. Por fari ĉi tion, uzu la opcion -l:

$ emem -D 'Kie estas ĝi' -K 'kukurboj, hundegoj, afiŝoj' -l eo LEGUMIN.md

Plena listo de la subtenitaj lingvoj de modernaj retumiloj troveblas ĉi tie.

Estas okazoj en kiu mi ne volas rompi la redaktadan iteracion laborante kun la enigaj dosieroj, kaj mi volas, ke la HTML-dosieroj nur kreiĝos kiam ajn novaj ŝanĝoj al la fontaj markdaŭnaj dosieroj realiĝas. Tiuokaze, mi alvokas la senpaŭzan reĝimon per la opcio -c:

$ emem -c LEGUMIN.md

La aliaj opcioj povas esti kombinitaj per la opcio -c por plifajnigi la eligon. Ekzemple, por munti senornaman eligon en senpaŭza reĝimo:

$ emem -Rpc LEGUMIN.md

emem kontrolas la ŝanĝojn en LEGUMIN.md po 200 ms . Se ŝanĝo estis eltrovita, ĝi rekunmetas la dosieron LEGUMIN.html. La tempolimo inter kontroloj povas esti ŝanĝita per la opcio -t. Por specifi unu minutan tempolimon:

$ emem -Rpc -t 1000 LEGUMIN.md

Kutime mi rulas emem jene:

$ emem -Fis dosiero.md

Fine, por vidi ĉiom da subtenitaj opcioj de emem, rulu:

$ emem --help

Finrimarkoj

Por ĉi tiu tuta blogo, mi povis atingi 90+ poentaron de Google PageSpeed Insights, «Mobile-Friendly»-pritakson de Google Mobile-Friendly Test, kaj ekonomian rangon de B de Pingdom. Se oni povas regi la TTT-servilajn parametrojn, oni eĉ povas atingi ekonomian rangon de A, kiam oni ekspluatas kaj specifas retumilan kaŝmemoron, kaj specifas la Vary: Accept-Encoding-ĉapon. Mi uzas GitHub Pages, do estas malsama sperto al mi.

Mi feliĉas pri la eligo kiun emem liveras. emem estas sufiĉe rapida kaj mi povas etendi ĝin facile. Mi eĉ uzas ĝin por miaj propraj kaj postenaj dokumentadoj. Mi ankaŭ uzas ĝin per emakso por krei TTT-versiojn de markdaŭnaj bufroj per shell-command kaj emacs-w3m. Por vidi emem en efektiva uzado, iru ĉi tien.

Se oni konas iom da Kloĵuro, forku ĝin kaj kodumu!