Markdown

Z JoggerWiki
Wersja z dnia 13:22, 17 lut 2010 autorstwa Wasacz (dyskusja | edycje) (js)

(różn.) ← poprzednia wersja | przejdź do aktualnej wersji (różn.) | następna wersja → (różn.)
Skocz do: nawigacji, wyszukiwania

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 = '';
	}
}

Linki zewnętrzne