k47.cz  — každý den dokud se vám to nezačne líbit
foto Praha výběr povídky kultura
twitter FB RSS

Jak začít s asciiblogem

3. 9. 2018 — k47 (♪)

Obsah:

  1. Zá­klady (přesně tady se na­chá­zíte
  2. Jak ge­ne­ro­vat blog z více sou­borů
  3. Upload skript
  4. Zbý­va­jící kon­fi­gu­rační di­rek­tivy
  5. Me­ta­in­for­mace, tagy, skryté tagy, su­per­tagy, články tagů, im­pli­kace, hi­e­rar­chie a auto-tagy
  6. Me­cha­nis­mus háčků pro vlastní roz­ší­ření

Jak jsem sli­bo­val, tak teď plním a při­ná­ším stručný návod jak začít po­u­ží­vat as­cii­blog pro vlastní pu­ris­tický blog. Je to velice jed­no­du­ché.

Nej­prve si po­jme­no­vaný nebo odsud stáh­něte zip po­sled­ního vydání (nebo sbt assembly) a někam ho roz­balte. Ob­sa­huje jeden jar, sou­bory s českým a an­g­lic­kým pře­kla­dem1 a sou­bory gallery.jscomments.php.

Teď musíte vy­tvo­řit tex­tový soubor, ze kte­rého se bude blog ge­ne­ro­vat. Po­jme­nujte ho třeba blog.txt, na­plňte ná­sle­du­jí­cími údaji a uložte v utf-8 kó­do­vání.

title Poznámky
baseUrl https://boxxy.k47.cz
inline!

Vítejte [2018/vitejte]
=====
2018-09-02
# uvítání

Vítejte na mém *novém blogu*, kterému pod kapotou běží "asciiblog":[a].

---

[* https://upload.wikimedia.org/wikipedia/commons/0/02/Welcome_mat_2.jpg .[main] *] *** vítejte (https://en.wikipedia.org/wiki/Welcome)

[a]: https://github.com/kaja47/asciiblog

Pak spusťte příkaz java -cp /cesta/k/asciiblog.jar asciiblog.Make blog.txt, který vy­ge­ne­ruje blog do právě ak­tiv­ního ad­re­sáře. Teď stačí jen tyto sou­bory nahrát na web a máte vy­sta­ráno. Je to takhle jed­no­du­ché.

Soubor se skládá ze dvou částí: Nahoře kon­fi­gu­rační di­rek­tivy. Dvě po­vinné a pak třetí („inline!“), která říká, že obsah blogu bude ná­sle­do­vat (je možné mít obsah ve více sou­bo­rech, de­taily níže). Pod nimi články blogu.

Článek začíná nad­pi­sem po kterém ná­sle­duje vo­li­telný slug, který se po­u­žije jako URL (pokud ho vy­ne­cháte, vy­ge­ne­ruje se ze jména článku), pod nímž musí být řádek rov­ní­tek a pak me­ta­in­for­mace vzta­žené k textu. Ty nej­běž­nější jsou: datum a tagy, ale nejsou jediné, k článku je možné přidat li­bo­volná uži­va­tel­ská data. Po prázd­ném řádku ná­sle­duje tex­tový obsah. Po­u­ží­vám znač­ko­vací jazyk vy­chá­ze­jící z Texy, který je na­vr­žený tak, aby ob­sa­ho­val jen mi­ni­mum vi­zu­ál­ního šumu a snadno se četl ve zdro­jové formě2 .

Text se skládá z bloků, které jsou vždy od­dě­leny prázd­ným řádkem, a jeden blok musí být vždy jed­noho typu. Vý­chozí typ je od­sta­vec, jde o blok textu na kterém není nic zvlášt­ního. Jeho obsah bude for­má­to­ván podle jed­no­du­chých pra­vi­del.

Odstavec může obsahovat *kurzívu*, *tučné písmo*, `neproporciální písmo`,
"titulek .(zobrazí se po najetí myši)", [|začerněné písmo|], poznámky jako
odkazy na číslovaný seznam[[1]] a "odkazy":[x]

Exis­tuje ně­ko­lik způ­sobů jak za­pi­so­vat odkazy. Buď ab­so­lut­ním URL, slugem článku nebo re­fe­rencí.

Odkazovat se můžete "absolutní cestou":[https://example.com/page.html], ale to
je poněkud nepřehledné. Text můžete zpřehlednit, pokud se "odkážete
referencí":[e], která bude rozvedena někde pod textem (nezáleží kde přesně,
asciiblog si s tím poradí).

Odkazy na jiné články blogu mohou být ve formě "absolutní
cesty":[https://test.k47.cz/2018/vitejte.html], ale to je příliš dlouhé a
zbytečné. Místo toho můžete použít "odkaz přes *slug*":[2018/vitejte] nebo
ještě lépe "referenci na slug":[v]. Zdrojový text je pak krásně přehledný.
Výsledný HTML dokument nicméně vypadá stejně nehledě na zvolený přístup.

Můžu taky použít <a href="v">HTML odkazy</a> a cíl se bude určovat stejnými
mechanismy.

[e]: https://example.com/page.html
[v]: 2018/vitejte

Jedna dů­le­žitá věc: slugy ne­fun­gují jako HTML odkazy, které jsou re­la­tivní vůči ak­tu­ál­nímu ad­re­sáři. Slug je vždy ab­so­lutní vůči kořeni webu. Po­u­ží­vejte celý slug a všechno bude fun­go­vat bez pro­blémů.

As­cii­blog kon­t­ro­luje zdali jsou všechny místní odkazy správné a chyby hlásí během ge­ne­ro­vání webu.

Další typy bloků:

Podnadpis
---------

Horizontální čára:

---

Blok obrázků:

[* img0.jpg *]
[* img1.jpg *] *** s popiskem
[* img2.jpg *] *** popisek může obsahovat #tagy
[* img3.jpg *] *** zdroj se může uvést do závorek (https://example.com)
[* img4.jpg .[main] *] *** hlavní obrázek, pěkně se roztáhne

> citovaný text
> typicky vyvedený kurzívou

--- autor citace (zarovnané doprava)

- nečíslovaný
- seznam
- různých
- položek
  (klidně víceřádkových)
- [|můžou|] *obsahovat* "veškeré":[e] `formátování`

1) číslovaný seznam
2) na něj odkazují [[1]] poznámky
3) asciiblog kontroluje, že každá poznámka má validní cíl[[666]]

| tabulka | různých | **věcí**
| 1       | 2       | 3

seznam referencí:

[e]: https://example.com/page.html
[v]: 2018/vitejte

Vy­ge­ne­ro­vaný web má vý­chozí vzhled, který se snaží na­po­do­bit vi­zu­ální podobu RFC do­ku­mentů. Pokud mu chcete vdech­nout trochu osobní jiskry, je třeba přidat ně­které ze tří kon­fi­gu­rač­ních di­rek­tiv style, headerfooter. Všechny musí přijít před inline!.

style| .b      { max-width:50em; font-family:serif; font-size:0.95em; line-height:1.6; padding:1.5em; border-right: 1px dotted gray }
style| a:hover { background-color: #FFA500 }
style| h1      { font-family:Georgia; font-size:2em; font-style: italic }
style| h2      { text-decoration: underline }
style| @media screen and (max-width: 800px) { .b { margin:0em 0em; font-size:0.8em } }
header| <h1><a href="index">Poznámky</a></h1>
footer| <hr><div style="color:gray;clear:both;text-align:center"> ««« kontakt: mail@example.com »»»</div>

Pokud di­rek­tiva končí znakem | je ví­ce­řád­ková, což se hodí právě pro zápis CSS stylů v di­rek­tivě style. header na­hradí vý­chozí hla­vičku na vrchu každé stránky, footer je pak při­po­jen na konec. headerfooter ob­sa­hují čisté HTML, ale odkazy jsou zpra­co­vá­vány, jak je vy­svět­leno výše.

Exis­tuje mnoho dal­ších di­rek­tiv. Zpo­čátku se budou hodit tyto:

# adresář do kterého je blog vygenerován
outDir /home/drgonzo/blog

# jak se má zobrazit hlavní stránka
index| fullArticles 7
index| archive

# mají se v RSS ukazovat celé články
fullArticlesInRss true

# jak se mají zobrazovat články v archivech
# link    - jen jako odkaz (výchozí)
# summary - začátek článku + obrázek
# full    - celý text článku
archiveFormat short

# jazyk blogu
# použije se ze souboru lang.${language}, který se nachází ve stejné složce
# jako asciiblog.jar
language cs

# povolení komentářů (vyžaduje aby na serveru bylo nainstalováno PHP)
allowComments true

# pokud je tohle nastavené na true, pod článkem se ukážou odkazy pro sdílení na
# některých sociálních sítích
shareLinks true

# pokud nastavíte openGraph na true nebo twitter.site na nějaké uživatelské
# jméno Twitteru, stránky budou při sdílení na sociálních sítích o něco hezčí.
openGraph true
twitter.site @kaja48

Ukázky: Kom­pletní zdroj blogu de­ad­beef.k47.cz


  1. Pokud tou­žíte po vzru­šení a/nebo ne­vě­říte ná­hod­ným jarům sta­že­ným z in­ter­netu, můžete snadno as­cii­blog sami zkom­pi­lo­vat. Na­in­sta­lujte Javu, Scalu a SBT a pak to roz­jeďte ve velkém: `git clone https://github.com/kaja47/as­cii­blog; cd as­cii­blog; sbt as­sem­bly;
  2. Přidat pod­poru pro další znač­ko­vací jazyky není ne­možné a v bu­doucnu chci přidat Mar­kdown nebo čisté HTML.
píše k47 & hosté, ascii@k47.cz