Składnia dokumentacji
*********************

Dokumentacja używa Markdowna i [składni Texy |https://texy.nette.org/syntax] z kilkoma rozszerzeniami.


Odnośniki
=========

Do odnośników wewnętrznych używa się zapisu w nawiasach kwadratowych `[link]`. Jest to albo postać z kreską pionową `[tekst odnośnika |cel odnośnika]`, albo postać skrócona `[tekst odnośnika]`, jeśli cel jest taki sam jak tekst (po zamianie na małe litery i myślniki):

- `[Nazwa strony]` -> `<a href="/en/page-name">Nazwa strony</a>`
- `[tekst odnośnika |Nazwa strony]` -> `<a href="/en/page-name">tekst odnośnika</a>`

Możemy linkować do innej wersji językowej albo innej sekcji. Sekcja oznacza bibliotekę Nette (np. `forms`, `latte` itd.) albo sekcje specjalne jak `best-practices`, `quickstart` itd.:

- `[cs:Nazwa strony]` -> `<a href="/cs/page-name">Nazwa strony</a>` (ta sama sekcja, inny język)
- `[tracy:Nazwa strony]` -> `<a href="//tracy.nette.org/en/page-name">Nazwa strony</a>` (inna sekcja, ten sam język)
- `[tracy:cs:Nazwa strony]` -> `<a href="//tracy.nette.org/cs/page-name">Nazwa strony</a>` (inna sekcja i język)

Można też wskazać konkretny nagłówek na stronie za pomocą `#`.

- `[#Nagłówek]` -> `<a href="#toc-heading">Nagłówek</a>` (nagłówek na bieżącej stronie)
- `[Nazwa strony#Nagłówek]` -> `<a href="/en/page-name#toc-heading">Nazwa strony</a>`

Odnośnik do strony głównej sekcji: (`@home` to specjalne określenie strony głównej sekcji)

- `[tekst odnośnika |@home]` -> `<a href="/en/">tekst odnośnika</a>`
- `[tekst odnośnika |tracy:]` -> `<a href="//tracy.nette.org/en/">tekst odnośnika</a>`


Odnośniki do dokumentacji API
-----------------------------

Używaj zawsze poniższego zapisu:

- `[api:Nette\SmartObject]` -> [api:Nette\SmartObject]
- `[api:Nette\Forms\Form::setTranslator()]` -> [api:Nette\Forms\Form::setTranslator()]
- `[api:Nette\Forms\Form::$onSubmit]` -> [api:Nette\Forms\Form::$onSubmit]
- `[api:Nette\Forms\Form::Required]` -> [api:Nette\Forms\Form::Required]

W pełni kwalifikowanych nazw używaj tylko przy pierwszej wzmiance. Przy kolejnych odnośnikach używaj nazwy uproszczonej:

- `[Form::setTranslator() |api:Nette\Forms\Form::setTranslator()]` -> [Form::setTranslator() |api:Nette\Forms\Form::setTranslator()]


Odnośniki do dokumentacji PHP
-----------------------------

- `[php:substr]` -> [php:substr]


Kod źródłowy
============

Blok kodu zaczyna się od <code>&#96;&#96;&#96;lang</code> i kończy <code>&#96;&#96;&#96;</code>. Wspierane języki to `php`, `latte`, `neon`, `html`, `css`, `js` i `sql`. Do wcięć zawsze używaj tabulatorów.

```
 ```php
	public function renderPage($id)
	{
	}
 ```
```

Możesz też podać nazwę pliku jako <code>&#96;&#96;&#96;php .{file: ArrayTest.php}</code>, a blok kodu wyrenderuje się tak:

```php .{file: ArrayTest.php}
public function renderPage($id)
{
}
```


Nagłówki
========

Górny nagłówek (nazwę strony) podkreślaj gwiazdkami (`*`). Do oddzielania sekcji używaj znaków równości (`=`). Nagłówki podkreślaj najpierw znakami równości (`=`), a potem myślnikami (`-`):

```
MVC Applications & Presenters
*****************************
...


Link Creation
=============
...


Links in Templates
------------------
...
```


Ramki i style
=============

Perex oznaczony klasą `.[perex]` .[perex]

Notatka oznaczona klasą `.[note]` .[note]

Wskazówka oznaczona klasą `.[tip]` .[tip]

Uwaga oznaczona klasą `.[caution]` .[caution]

Mocne ostrzeżenie oznaczone klasą `.[warning]` .[warning]

Numer wersji `.{data-version:2.4.10}` .{data-version:2.4.10}

Klasy należy zapisywać przed linią, której dotyczą:

```
.[perex]
To jest perex.
```

Zwróć uwagę, że ramki jak `.[tip]` przyciągają uwagę, dlatego powinny służyć do podkreślania ważnych informacji, a nie mniej istotnych szczegółów. Używaj ich oszczędnie.


Spis treści
===========

Spis treści (odnośniki w prawym pasku bocznym) generowany jest automatycznie dla wszystkich stron przekraczających rozmiar 4000 bajtów. To domyślne zachowanie da się zmienić [metatagiem |#Metatagi] `{{toc}}`. Tekst do spisu treści brany jest domyślnie bezpośrednio z nagłówków, ale można wyświetlić inny tekst modyfikatorem `.{toc}`, co przydaje się przy dłuższych nagłówkach.

```


Long and Intelligent Heading .{toc: A Different Text for TOC}
=============================================================
```


Metatagi
========

- Ustawienie własnego tytułu strony (w `<title>` i okruszkach): `{{title: Inna nazwa}}`
- Przekierowanie: `{{redirect: pla:cs}}` - patrz [#Odnośniki]
- Wymuszenie `{{toc}}` albo wyłączenie `{{toc: no}}` automatycznego spisu treści (ramka z odnośnikami do nagłówków).
- Ustawienie lewego menu `{{leftbar: utils:@left-menu}}` albo jego wyłączenie `{{leftbar: no}}`.

{{priority: -1}}