Jak začít s asciiblogem

3. 9. 2018 — k47

Obsah:

Základy (přesně tady se nacházíte)
Jak generovat blog z více souborů
Upload skript
Zbývající konfigurační direktivy
Metainformace, tagy, skryté tagy, supertagy, články tagů, implikace, hierarchie a auto-tagy
Mechanismus háčků pro vlastní rozšíření

Jak jsem sliboval, tak teď plním a přináším stručný návod jak začít používat asciiblog pro vlastní puristický blog. Je to velice jednoduché.

Nejprve si pojmenovaný nebo odsud stáhněte zip posledního vydání (nebo sbt assembly) a někam ho rozbalte. Obsahuje jeden jar, soubory s českým a anglickým překladem¹ a soubory gallery.js a comments.php.

Teď musíte vytvořit textový soubor, ze kterého se bude blog generovat. Pojmenujte ho třeba blog.txt, naplňte následujícími údaji a uložte v utf-8 kódová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ý vygeneruje blog do právě aktivního adresáře. Teď stačí jen tyto soubory nahrát na web a máte vystaráno. Je to takhle jednoduché.

Soubor se skládá ze dvou částí: Nahoře konfigurační direktivy. Dvě povinné a pak třetí („inline!“), která říká, že obsah blogu bude následovat (je možné mít obsah ve více souborech, detaily níže). Pod nimi články blogu.

Článek začíná nadpisem po kterém následuje volitelný slug, který se použije jako URL (pokud ho vynecháte, vygeneruje se ze jména článku), pod nímž musí být řádek rovnítek a pak metainformace vztažené k textu. Ty nejběžnější jsou: datum a tagy, ale nejsou jediné, k článku je možné přidat libovolná uživatelská data. Po prázdném řádku následuje textový obsah. Používám značkovací jazyk vycházející z Texy, který je navržený tak, aby obsahoval jen minimum vizuálního šumu a snadno se četl ve zdrojové formě² .

Text se skládá z bloků, které jsou vždy odděleny prázdným řádkem, a jeden blok musí být vždy jednoho typu. Výchozí typ je odstavec, jde o blok textu na kterém není nic zvláštního. Jeho obsah bude formátován podle jednoduchých pravidel.

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]

Existuje několik způsobů jak zapisovat odkazy. Buď absolutním URL, slugem článku nebo referencí.

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 nefungují jako HTML odkazy, které jsou relativní vůči aktuálnímu adresáři. Slug je vždy absolutní vůči kořeni webu. Používejte celý slug a všechno bude fungovat bez problémů.

Asciiblog kontroluje zdali jsou všechny místní odkazy správné a chyby hlásí během generová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

Vygenerovaný web má výchozí vzhled, který se snaží napodobit vizuální podobu RFC dokumentů. Pokud mu chcete vdechnout trochu osobní jiskry, je třeba přidat některé ze tří konfiguračních direktiv style, header a footer. 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 direktiva končí znakem | je víceřádková, což se hodí právě pro zápis CSS stylů v direktivě style. header nahradí výchozí hlavičku na vrchu každé stránky, footer je pak připojen na konec. header a footer obsahují čisté HTML, ale odkazy jsou zpracovávány, jak je vysvětleno výše.

Existuje mnoho dalších direktiv. 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: Kompletní zdroj blogu deadbeef.k47.cz

Pokud toužíte po vzrušení a/nebo nevěříte náhodným jarům staženým z internetu, můžete snadno asciiblog sami zkompilovat. Nainstalujte Javu, Scalu a SBT a pak to rozjeďte ve velkém:

git clone https://github.com/kaja47/asciiblog; cd asciiblog; sbt assembly;

Přidat podporu pro další značkovací jazyky není nemožné a v budoucnu chci přidat Markdown nebo čisté HTML.