Markdown
Spis treści
Informacje ogólne
Markdown jest prostym językiem znacznikowym przeznaczonym do formatowania zwykłego tekstu, konwertowanego następnie do poprawnego składniowo kodu HTML. Markdown udostępniany jest na licencji pochodnej od BSD.
Markdown na Joggerze
Można wykorzystać Markdown do formatowania treści wpisów lub treści komentarzy na własnym joggerze.
Markdown wykorzystywany dla komentarzy nie udostępnia możliwości formatowania nagłówków, poziomych linii ani obrazków. Ponadto, automatyczna korekta znaków typograficznych została wyłączona, gdyż stosowanie jej w komentarzach powodowało różnego rodzaju pomyłki.
Włączyć lub wyłączyć Markdown można w panelu administracyjnym:
Formatowanie treści wpisów lub treści komentarzy za pomocą Textile nie jest już dostępne, ale nie ma to wpływu na dotychczasowe wpisy i komentarze.
Dostępna składnia
Elementy blokowe
Akapity i podziały linii
Akapity (znaczniki <p/>) tworzone są z bloków tekstu, które oddzielone są za pomocą co najmniej jednej pustej linii lub linii zawierającej wyłącznie spacje lub wcięcia.
Podział linii (znacznik <br/>) tworzony jest w miejscu nowej linii odmiennie niż w przypadku klasycznego Markdowna, który wymagał poprzedzenia go co najmniej jedną spacją.
Nagłówki
Dostępne są dwie metody formatowania nagłówków (znaczniki: <h1/>, <h2/>, itd.):
Nagłówek pierwszego rzędu ========================= Nagłówek drugiego rzędu -----------------------
# Nagłówek pierwszego rzędu ## Nagłówek drugiego rzędu
Dla drugiego sposobu nagłówki pozostałych poziomów (1-6.) tworzy się analogicznie.
Bloki kodu
Preformatowane bloki kodu (znaczniki: <pre><code/></pre>) tworzone są na podstawie tekstu poprzedzonego co najmniej czterema spacjami lub co najmniej jednym wcięciem.
Przykładowy blok kodu
Formatowanie Markdown wewnątrz takiego bloku zostanie zignorowane.
Linie poziome
Linie poziome (znaczniki <hr/>) można tworzyć za pomocą powtórzonego co najmniej trzy razy dowolnego ze znaków znaków: pauza (-), gwiazdka (*), podkreślenie (_). Opcjonalnie, znaki te mogą być oddzielone spacjami. Przykłady:
*** * * * ********** --------------------
Elementy liniowe
Odnośniki
Dostępnych jest kilka metod formatowania odnośników (znaczniki <a/>):
- Standardowy odnośnik:
[Tytuł](http://example.com/). - Odnośnik z etykietą ekranową:
[Tytuł](http://example.com/ "Etykieta"). - Odnośnik bez zdefiniowanego tytułu:
<http://example.com/>.
Odnośniki do adresów e-mail zostaną dodatkowo zabezpieczone przed zautomatyzowanymi metodami zbierania adresów e-mail z witryn internetowych. Należy jednak pamiętać, że zabezpieczenie nie jest całkowicie skuteczne.
Istnieje także możliwość określania docelowego adresu URI za pomocą referencji.
Emfaza i silna emfaza
Emfazę (znacznik <em/>) i silną emfazę (znacznik <strong/>) można tworzyć za pomocą znaków: gwiazdka (*), podreślenie (_):
- Emfaza:
*emfaza*,_emfaza_. - Silna emfaza:
**silna emfaza**,__silna emfaza__.
Wymienione znaki poprzedzone odwrotnym ukośnikiem są ignorowane.
Kod
Kod umieszczany wewnątrz bloku tekstu (znacznik <code/>) tworzy się za pomocą znaków słabego akcentu (`). Zdublowanie tych znaków po obydwu stronach formatowanego tekstu powoduje, że znajdujące się pomiędzy nimi pojedyncze znaki słabego akcentu są ignorowane.
- Standardowy znacznik kodu:
`kod`,` kod `. - Rozszerzony znacznik kodu:
``kod ze znakiem `, czyli słabego akcentu``, `` kod ze znakiem `, czyli słabego akcentu ``.
Podgląd komentarzy w czasie rzeczywistym
Showdown jest implementacją Markdowna w języku JavaScript. Można go wykorzystać do tworzenia podglądu komentarza w czasie jego pisania. Po pobraniu archiwum ZIP na dysk i rozpakowaniu go, wystarczy wgrać na serwer Joggera jeden z plików showdown.js (w katalogu src znajduje się pełen kod, zaś w katalogu compressed wersja zaciemniona) oraz umieścić do niego odwołanie w nagłówku szablonu komentarzy.
Przykładowa implementacja może wyglądać tak:
// funkcja addEvent, której autorem jest John Resig:
// http://www.quirksmode.org/blog/archives/2005/10/_and_the_winner_1.html
try {
// odnajdujemy pole tekstowe i blok z podglądem
var commbody = document.getElementById('commbody');
var commprev = document.getElementById('comment-preview-box');
// jeśli pole tekstowe nie zostało znalezione, przerywamy działanie
if (!commbody || !commprev)
throw new Error();
// tworzymy instancję dla konwertera
var converter = new Showdown.converter();
// przechwytujemy zdarzenie klawiatury
addEvent(commbody, 'keyup', (function(p, c) {
return function() {
// konwertujemy komentarz z formatu Markdown do kodu HTML
// blok z podglądem aktualizujemy o wygenerowany kod HTML
p.innerHTML = c.makeHtml(this.value);
};
})(commprev, converter));
}
catch (e) {
if (commprev) {
// w razie problemów można wyczyścić zawartość bloku z podglądem
commprev.innerHTML = '';
}
}
