Cikkírás gyorsan és könnyen
Copyright © 2010 Páli Gábor. Minden jog fenntartva.
Tartalomjegyzék
Bevezetés
A markdown formátumot a lehető legkönnyebben olvashatónak és szerkeszhetőnek tervezték. Az ilyen formában készült dokumentumokat szinte közvetlenül lehet publikálni anélkül, hogy további jelölési (,,markup'') vagy formázási utasításokkal látnánk el. Mindezek az információk magában a szöveg kialakításában jelennek meg rejtetten, és a markdown feldolgozó tulajdonképpen csak a korábban a forrásban kialakított formázást igyekszik átültetni további más (HTML, PDF, RTF, stb.) formátumokra.
Ezért nagyon fontos a szöveg egységes és logikus tagolása, valamint bizonyos alapvető konvenciók ismerete a szerkesztés során. Ezek legtöbbje azonban viszonylag intuitív és gyorsan elsajátítható, ezek bemutatásában segít elsősorban ez a leírás.
Bekezdések és sortörések
A bekezdések egy vagy több egymást követő sorból állnak, amelyeket 1 vagy több üres sor választ el. A bekezdéseket nem kell behúzni tabulátorok vagy szóközök használatával, mivel annak külön jelentősége van. A bekezdések sorai automatikusan egyetlen összefüggő szöveggé állnak össze a formázás során. Ezért ha sortörést szeretnénk valahol elhelyezni bennük, akkor azt külön jelöljünk kell az adott sor végén legalább két szóköz karakter segítségével.
Címek
A szövegben címeket kétféleképpen is lehet jelezni: aláhúzással vagy kettőskeresztekkel, amelyek akár ízlés szerint kombinálhatóak egyetlen forráson belül.
Az aláhúzások használata során a kettős aláhúzás (egyenlőségjelek) fogja jelenteni az első szintű címet, az egyszeres (mínuszjelek) pedig a második szintű címet. Az aláhúzásnak nem kötelező azonos hosszúságnak lennie a címmel.
Ez egy főcím
============
Ez pedig itt egy alcím
----------------------
A kettőskereszttel további négy szintet tudunk használni. Ehhez csupán a cím elé kell írnunk a cím szintjének megfelelő mennyiségű keresztet.
# Első szintű cím (főcím)
## Második szintű cím (alcím)
###### Hatodik szintű cím
Idézetblokkok
Az idézetblokkok írásához > (relációjel) karaktereket tudunk használni, hasonlóan
például az elektronikus levelek esetén megszokott stílushoz. Ehhez mindössze
az idézni kívánt sorokat ezzel a karakterrel kell kezdeni. Remekül lehet
alkalmazni például megjegyzések írásánál.
> Megjegyzés: Az optimális teljesítmény érdekében olvassunk utána a
> konfigurációs beállításoknak a dokumentációban.
>
> Még ez a bekezdés is hozzá tartozik a blokkhoz.
Az idézetblokkok egymásba ágyazhatóak további szintek bevezetésével.
> Megjegyzés: Az optimális teljesítmény érdekében olvassunk utána a
> konfigurációs beállításoknak a dokumentációban.
>
> Még ez a bekezdés is hozzá tartozik a blokkhoz.
>
> > Megjegyzés megjegyzése: De tényleg ne felejtsük el elolvasni
> > a dokumentációt!
Az idézetblokkok gond nélkül használhatóak a markdownban alkalmazható formázások.
> **Megjegyzés:** Az optimális teljesítmény érdekében olvassunk utána a
> konfigurációs beállításoknak a dokumentációban.
Felsorolások
Markdownban lehetőség van sorszámozott és sorszámozás nélküli felsorolások
írására. A sorszámozás nélküli felsorolások szerepelhetnek csillaggal (*),
pluszjellel (+), mínuszjellel (-).
Például:
* Piros
* Fehér
* Zöld
Vagy:
+ Piros
+ Fehér
+ Zöld
Vagy:
- Piros
- Fehér
- Zöld
A sorszámozott felsorolások elemeit pedig számmal és egy ponttal (.) tudjuk
jelölni. A konkrét számok igazából nem bírnak jelentéssel, ezért nyugodtan
használhatjuk mindig ugyanazt a felsorolások elemeinek írásakor.
9. Első elem
9. Második elem
9. Harmadik elem
A felsorolások elemeinek általában a bal szélső margón kell kezdődniük, de egészen három szóközig be lehet húzni ezeket. A bevezető karakter után viszont mindig tenni kell legalább egy szóközt.
A hosszabb elemekhez tartozó szöveget nyugodtan tördelhetjük manuálisan, ekkor viszont ügyeljünk arra, hogy az egymáshoz tartozó szövegrészek behúzása azonos legyen.
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
Ez különösen abban az esetben fontos, amikor egy felsorolásbeli elem több bekezdésből áll.
1. This is a list item with two paragraphs. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
sit amet velit.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
Előfordulhat, hogy más, behúzás igénylő formázást akarunk használni (lásd később) a felsorolások írásánál. Ekkor ügyelnünk kell arra, hogy a behúzás mértéke mindig a felsorolás behúzási szintjénél kezdődik. Például a kódrészletek mellékelésekor tulajdonképpen kétszer kell behúznunk a szöveget.
* Ha kódrészletet akarunk felsorolásba betenni, akkor ezt így
fel írnunk a forrásban.
<az adott kódrészlet>
Érdemes még megemlíteni, hogy a jelölés stílusából fakadóan adódhat, hogy akaratlanul is sorszámozott lista generálódik bizonyos helyeken.
1984. George Orwell regénye.
Ezt úgy tudjuk kivédeni, ha a pont elé egy backslash (\) karaktert teszünk.
1984\. George Orwell regénye.
Formázatlan szövegrészek
Forráskódok, konfigurációs állományok vagy parancsok bemutatásánál szükségünk lehet arra, hogy az adott szövegrész ne formázódjon meg. Ekkor lényegében a szokásos bekezdések helyett pontosan az és úgy jelenik meg, ahogy azt az dokumentum forrásában megadtuk.
Ehhez mindössze 4 szóközzel kell behúzni az adott szövegrészt.
Ez egy átlagos bekezdés.
Ez egy formázatlan bekezdés.
Itt sincs formázás.
Az eredményben természetesen minden 4 szóközzel bentebb jelenik meg, mivel a
behúzás maga a formázási utasítás. A legközelebbi behúzás nélküli sorig tart.
Megjegyezendő, hogy a kimeneti formátumtól függően bizonyos szimbólumok
kicserélődnek a nekik megfelelő ábrázolásra (például HTML esetében &, <, >
a karakterből &, <, > karakteres entitások lesznek) a
formázatlanság megőrzése érdekében.
Függőleges elválasztók
A szöveg tagolására tudunk függőleges elválasztókat is használni, amelyekhez
elegendő csupán 3 vagy több mínuszjelet (-), csillagot (*) vagy
aláhúzásjelet (_) egymás után írnunk. Az alábbiak mindegyike egy ilyet
hoz létre.
* * *
***
- - -
-------------------
___________________
Linkek
A markdown formátum a linkek írásának kétfajta módját támogatja: a beágyazott linkeket és a hivatkozásokat. A link szövegét mind a két esetben [szögletes zárójelek között] kell írnunk.
Beágyazott linket úgy tudunk írni, ha a szögletes zárójel után közvetlenül zárójelek között megadjuk a linket URL-jét. Mellette opcionálisan még szerepelhet a link elnevezése idézőjelek között.
Ez egy [egyszerű példa](http://bsd.hu/ "BSD.hu főoldal") arra, hogy
miként lehet beágyazott linkeket készíteni.
Ezzel a módszerrel természetesen relatív (index.html) és abszolút
(http://bsd.hu/index.html) módon is tudunk oldalakra mutatni, tehát ügyesen
használható például több összefüggő dokumentum összekötésére egyetlen holnapon
belül.
Emellett még a linkeket írhatjuk hivatkozással. Ekkor nem zárójelek között adunk meg egy konkrét linket, hanem helyett annak az azonosítóját szögletes zárójelek között.
Ebben a példában a linket [hivatkozással][azonosito] hozunk
létre.
Ezután a dokumentumban bárhol definiálhatjuk az adott azonosítóhoz tartozó linket.
[azonosito]: http://bsd.hu/ "BSD.hu főoldal"
Az ilyen típusú linkeket egyébként a markdowntól megszokott módon több más is írhatjuk, jelentésük megegyezik.
[azonosito]: http://bsd.hu/ "BSD.hu főoldal"
[azonosito]: http://bsd.hu/ 'BSD.hu főoldal'
[azonosito]: http://bsd.hu/ (BSD.hu főoldal)
Valamint az URL még szerepelhet relációs jelek között.
[azonosito]: <http://bsd.hu/> "BSD.hu főoldal"
Hosszabb URL-ek esetében pedig mindezt sortöréssel tehetjük olvashatóbbá.
[azonosito]: <http://bsd.hu/egy/nagyon/hosszu/eleresi/ut>
"BSD.hu főoldal"
Ezek a definíciók a kimeneti formátumban nem jelennek meg, csupán segédinformációként vannak jelen a dokumentumban. A definíciók azonosítójában betűk, számjegyek, írásjelek és szóközök is szerepelhetnek, azonban a kis- és nagybetűk között a markdown nem tesz különbséget. Ennek megfelelően az alábbi két link teljesen ugyanazt jelenti.
[egyik hivatkozás][a]
[másik hivatkozás][A]
Ha a link szövege és a hozzá tartozó azonosító megegyezik, akkor
implicit linkek segítségével rövidíteni tudunk. Ilyenkor elengedő csak
egy üres szögletes zárójelpárt megadnunk. Például, ha a ,,Google'' szót
szeretnénk a google.com oldalra linkelni,a következőket kell írnunk.
[Google][]
Majd definiálnunk a megfelelő linket.
[Google]: http://www.google.com/
Mivel a linkekhez tartozó szövegekben szóköz, és ezáltal több szó is szerepelhet, ez a megoldás természetesen működik olyankor is.
Kiemelések
A markdown a csillagokat (*) és az aláhúzásjeleket (_) kiemelést jelző
szimbólumoknak tekinti. Ennek megfelelően tehát a * és _ karakterek között
leírt szöveg az adott kimeneti formátum szerint kiemeléssel (általában dőlten)
jelenik meg.
*egyszeres csillagozás*
_egyszeres aláhúzás_
Amennyiben ezeket kettőzzük, akkor az erősebb kiemelést (általában kövéren szedett betűket) eredményez.
**kétszeres csillagozás**
__kétszeres aláhúzás__
Bármelyik változat alkalmazható, egyetlen fontos elvárás, hogy ugyanazzal a fajta karakterrel zárjuk le a kiemelést, mint amelyikkel elkezdtük. Kiemelést egyébként szavakon belül jelölhetünk.
le*het*séges
Ha nem szeretnénk kiemelni, viszont szükségünk van csillagokra vagy
aláhúzásjelekre a szövegen belül, akkor a backslash (\) karaktert kell
segítségül hívnunk.
\*Ez a szöveg nem emelődik ki, csak csillagok lesznek előtte és utána.\*
Formázatlan részek
A szövegben lehetőségünk nyílik formázatlan részek beszúrására az ún. backtick (`) karakterrel. Ez jól használható például függvények neveinek kiemelésére folyó szövegen belül.
A kiíratáshoz használjük a `printf()` függvényt.
Ha magát a backtick karaktert akarjuk egy formázatlan szövegrészben használni, akkor több backtick segítségével tudjuk jelölni az azt körülvevő környezetet.
``Ebben a szövegben van egy formázatlan (`) backtick karakter.``
A backtick karakterekkel elválasztott szövegrészek szóközöket is tartalmazhatnak -- egyet a nyitás után, egyet pedig a zárás előtt. Így akár egyetlen backtick is írható formázás nélkül.
`` ` ``
Vagy backtick karaktert tartalmazó szövegnél.
`` `izé` ``
A korábbiakban írtuk szerint a formázatlan részekben az adott kimeneti formátum számára jelentéssel bíró karakterek automatikusan kicserélődnek a nekik megfelelő reprezentációjukra.
Képek
Az alap markdown jelölés szerint a képek a linkekhez hasonlóan illeszhetőek be a dokumentumokba. Ezért a képeket is lehet beágyazottan vagy hivatkozással linkelni.
Képeket az alábbi mintájára tudunk beágyazni.
Tehát a jelölés módja tulajdonképpen majdnem ugyanaz, mint egy link esetében,
egyedüli különbség annyi, hogy felkiáltójellel (!) vezetjük be. Az
értelmezésében pedig az eltérés, hogy a link szövege helyett helyettesítő
szöveget adunk meg, amely akkor jelenik meg, ha az adott formátumban vagy
annak megjelenítőjében a kép nem mutatható meg valamiért.
A képek referencia stílusú beillesztése az alábbi módon végezhető el.
![Helyettesítő szöveg][azonosito]
Ahol az azonosito a hivatkozni kívánt képhez tartozó, a dokumentum valamelyik
részén definiált egyedi azonosító. Ilyeneket a linkeknél mutatott módon tudunk
létrehozni.
[azonosito]: /a/kep/eleresi/utja/kep.jpg "Opcionális elnevezés"
Automatikus linkek
A markdown a további könnyítés érdekében támogatja a szövegben előforduló URL-ek ,,automatikus'' konverzióját. Ehhez mindössze elegendő az adott oldal vagy elektronikus postafiók címét relációs jelek közé tenni. Ekkor a konkrét hivatkozás linkként jelenik meg a szövegben.
<http://bsd.hu/>
Az email címek linkké alakítása is hasonlóképpen oldható meg.
<pgj@bsd.hu>
Backslash-elés
A markdown forrásokban külön jelentéssel bíró szimbólumokat egy backslash karakter segítségével tudjuk a szövegben használni, vagyis kikapcsolni a általuk képviselt formázási utasítást.
\*Ezek a csillagok nem csinálnak semmit, csak megjelennek a
szöveg részeként.\*
Ezen további karakterek esetén alkalmazható ez a stílusú jelölés:
- backslash:
\, - backtick:
`, - csillag:
*, - aláhúzásjel:
_, - hullámos zárójelek:
{és}, - szögletes zárójelek:
[és], - zárójelek:
(és), - kettőskereszt:
#, - pluszjel:
+, - mínuszjel:
-, - pont:
., - felkiáltójel:
!.
Szoftverek
A markdownban írt forrásokat több különböző implementációval is lehet tesztelni, ezek közül kettőt tudunk konkrétan javasolni.
A Markdown egy egyszerű konverziós eszköz, amellyel XHTML vagy HTML oldalakat tudunk készíteni dokumentumainkból. Ez tekinthető a markdown formátum refencia implementációjának.
A Pandoc egy rengeteg be- és kimeneti formátumot támogató konverziós szoftver, amely többek között markdown olvasására is képes, valamint támogatja annak egy speciális bővítését. Alapvetően gyorsabb, mint a Markdown, és ráadásul a honlapján keresztül közvetlenül ki is próbálható. Csak UTF-8 kódolású állományokat olvas.
