Синтаксис документации
**********************
Документация использует Markdown и [синтаксис Texy |https://texy.deegee.dev/syntax] с несколькими дополнениями.
Ссылки
======
Для внутренних ссылок используется запись в квадратных скобках `[link]`. Это либо вид с вертикальной чертой `[текст ссылки |цель ссылки]`, либо сокращённый вид `[текст ссылки]`, если цель совпадает с текстом (после преобразования в строчные буквы и дефисы):
- `[Page name]` -> `<a href="/en/page-name">Page name</a>`
- `[link text |Page name]` -> `<a href="/en/page-name">link text</a>`
Мы можем сослаться на другую языковую версию или другой раздел. Раздел означает библиотеку Nette (например, `forms`, `latte` и т. д.) или особые разделы вроде `best-practices`, `quickstart` и т. п.:
- `[cs:Page name]` -> `<a href="/cs/page-name">Page name</a>` (тот же раздел, другой язык)
- `[tracy:Page name]` -> `<a href="//tracy.nette.org/en/page-name">Page name</a>` (другой раздел, тот же язык)
- `[tracy:cs:Page name]` -> `<a href="//tracy.nette.org/cs/page-name">Page name</a>` (другой раздел и язык)
С помощью `#` можно нацелиться и на конкретный заголовок на странице.
- `[#Heading]` -> `<a href="#toc-heading">Heading</a>` (заголовок на текущей странице)
- `[Page name#Heading]` -> `<a href="/en/page-name#toc-heading">Page name</a>`
Ссылка на главную страницу раздела: (`@home` - особое обозначение главной страницы раздела)
- `[link text |@home]` -> `<a href="/en/">link text</a>`
- `[link text |tracy:]` -> `<a href="//tracy.nette.org/en/">link text</a>`
Ссылки на документацию API
--------------------------
Всегда используйте такую запись:
- `[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]
Полные имена используйте только при первом упоминании. Для дальнейших ссылок используйте упрощённое имя:
- `[Form::setTranslator() |api:Nette\Forms\Form::setTranslator()]` -> [Form::setTranslator() |api:Nette\Forms\Form::setTranslator()]
Ссылки на документацию PHP
--------------------------
- `[php:substr]` -> [php:substr]
Исходный код
============
Блок кода начинается с <code>```lang</code> и заканчивается <code>```</code>. Поддерживаемые языки: `php`, `latte`, `neon`, `html`, `css`, `js` и `sql`. Для отступов всегда используйте табуляции.
```
```php
public function renderPage($id)
{
}
```
```
Можно указать и имя файла как <code>```php .{file: ArrayTest.php}</code>, и блок кода отрисуется так:
```php .{file: ArrayTest.php}
public function renderPage($id)
{
}
```
Заголовки
=========
Самый верхний заголовок (имя страницы) подчёркивайте звёздочками (`*`). Для разделения секций используйте знаки равенства (`=`). Заголовки подчёркивайте сначала знаками равенства (`=`), а затем дефисами (`-`):
```
MVC Applications & Presenters
*****************************
...
Link Creation
=============
...
Links in Templates
------------------
...
```
Блоки и стили
=============
Перекс, помеченный классом `.[perex]` .[perex]
Замечание, помеченное классом `.[note]` .[note]
Совет, помеченный классом `.[tip]` .[tip]
Предостережение, помеченное классом `.[caution]` .[caution]
Строгое предупреждение, помеченное классом `.[warning]` .[warning]
Номер версии `.{data-version:2.4.10}` .{data-version:2.4.10}
Классы следует писать перед строкой, к которой они относятся:
```
.[perex]
Это перекс.
```
Учтите, что блоки вроде `.[tip]` привлекают внимание и поэтому должны использоваться для выделения важных сведений, а не менее значимых подробностей. Используйте их умеренно.
Содержание
==========
Содержание (ссылки в правой колонке) порождается автоматически для всех страниц размером более 4000 байт. Это поведение по умолчанию можно изменить [метатегом |#Метатеги] `{{toc}}`. Текст для содержания по умолчанию берётся прямо из заголовков, но можно вывести другой текст модификатором `.{toc}`, что полезно для более длинных заголовков.
```
Long and Intelligent Heading .{toc: A Different Text for TOC}
=============================================================
```
Метатеги
========
- Задать собственный заголовок страницы (в `<title>` и хлебных крошках): `{{title: Another name}}`
- Перенаправление: `{{redirect: pla:cs}}` - см. [#Ссылки]
- Принудительно включить `{{toc}}` или отключить `{{toc: no}}` автоматическое содержание (блок со ссылками на заголовки).
- Задать левое меню `{{leftbar: utils:@left-menu}}` или отключить его `{{leftbar: no}}`.
{{priority: -1}}
Синтаксис документации
Документация использует Markdown и синтаксис Texy
с несколькими дополнениями.
Ссылки
Для внутренних ссылок используется запись в квадратных скобках
[link]. Это либо вид с вертикальной чертой
[текст ссылки |цель ссылки], либо сокращённый вид
[текст ссылки], если цель совпадает с текстом (после
преобразования в строчные буквы и дефисы):
[Page name] → <a href="/en/page-name">Page name</a>
[link text |Page name] → <a href="/en/page-name">link text</a>
Мы можем сослаться на другую языковую версию или другой раздел.
Раздел означает библиотеку Nette (например, forms, latte и т. д.)
или особые разделы вроде best-practices, quickstart и т. п.:
[cs:Page name] → <a href="/cs/page-name">Page name</a> (тот же раздел,
другой язык)
[tracy:Page name] → <a href="//tracy.nette.org/en/page-name">Page name</a>
(другой раздел, тот же язык)
[tracy:cs:Page name] → <a href="//tracy.nette.org/cs/page-name">Page name</a>
(другой раздел и язык)
С помощью # можно нацелиться и на конкретный заголовок на
странице.
[#Heading] → <a href="#toc-heading">Heading</a> (заголовок на
текущей странице)
[Page name#Heading] → <a href="/en/page-name#toc-heading">Page name</a>
Ссылка на главную страницу раздела: (@home – особое обозначение
главной страницы раздела)
[link text |@home] → <a href="/en/">link text</a>
[link text |tracy:] → <a href="//tracy.nette.org/en/">link text</a>
Ссылки на документацию API
Всегда используйте такую запись:
Полные имена используйте только при первом упоминании. Для
дальнейших ссылок используйте упрощённое имя:
Ссылки на документацию PHP
Исходный код
Блок кода начинается с ```lang и заканчивается ```.
Поддерживаемые языки: php, latte, neon, html,
css, js и sql. Для отступов всегда используйте
табуляции.
```php
public function renderPage($id)
{
}
```
Можно указать и имя файла как ```php .{file: ArrayTest.php}, и блок кода
отрисуется так:
public function renderPage($id)
{
}
Заголовки
Самый верхний заголовок (имя страницы) подчёркивайте звёздочками
(*). Для разделения секций используйте знаки равенства (=).
Заголовки подчёркивайте сначала знаками равенства (=), а затем
дефисами (-):
MVC Applications & Presenters
*****************************
...
Link Creation
=============
...
Links in Templates
------------------
...
Блоки и стили
Перекс, помеченный классом .[perex]
Замечание, помеченное классом .[note]
Совет, помеченный классом .[tip]
Предостережение, помеченное классом .[caution]
Строгое предупреждение, помеченное классом .[warning]
Номер версии .{data-version:2.4.10}
Классы следует писать перед строкой, к которой они относятся:
.[perex]
Это перекс.
Учтите, что блоки вроде .[tip] привлекают внимание и поэтому
должны использоваться для выделения важных сведений, а не менее
значимых подробностей. Используйте их умеренно.
Содержание
Содержание (ссылки в правой колонке) порождается автоматически для
всех страниц размером более 4000 байт. Это поведение по умолчанию можно
изменить метатегом {{toc}}. Текст для содержания по
умолчанию берётся прямо из заголовков, но можно вывести другой текст
модификатором .{toc}, что полезно для более длинных заголовков.
Long and Intelligent Heading .{toc: A Different Text for TOC}
=============================================================
- Задать собственный заголовок страницы (в
<title> и хлебных
крошках): {{title: Another name}}
- Перенаправление:
{{redirect: pla:cs}} – см. Ссылки
- Принудительно включить
{{toc}} или отключить {{toc: no}}
автоматическое содержание (блок со ссылками на заголовки).
- Задать левое меню
{{leftbar: utils:@left-menu}} или отключить его
{{leftbar: no}}.