Documentation Syntax
Documentation uses Markdown & Texy syntax with several enhancements.
Links
For internal links, notation in square brackets [link]
is used. This is either in the form with a pipe
[link text |link target]
, or in the abbreviated form [link text]
if the target is the same as the text
(after transformation to lowercase and hyphens):
[Page name]
→<a href="/en/page-name">Page name</a>
[link text |Page name]
→<a href="/en/page-name">link text</a>
We can link to another language version or another section. A section refers to a Nette library (e.g., forms
,
latte
, etc.) or special sections like best-practices
, quickstart
, etc.:
[cs:Page name]
→<a href="/cs/page-name">Page name</a>
(same section, different language)[tracy:Page name]
→<a href="//tracy.nette.org/en/page-name">Page name</a>
(different section, same language)[tracy:cs:Page name]
→<a href="//tracy.nette.org/cs/page-name">Page name</a>
(different section and language)
It's also possible to target a specific heading on the page using #
.
[#Heading]
→<a href="#toc-heading">Heading</a>
(heading on the current page)[Page name#Heading]
→<a href="/en/page-name#toc-heading">Page name</a>
Link to the section's home page: (@home
is a special term for the section's home page)
[link text |@home]
→<a href="/en/">link text</a>
[link text |tracy:]
→<a href="//tracy.nette.org/en/">link text</a>
Links to API Documentation
Always use the following notation:
[api:Nette\SmartObject]
→ Nette\SmartObject[api:Nette\Forms\Form::setTranslator()]
→ Nette\Forms\Form::setTranslator()[api:Nette\Forms\Form::$onSubmit]
→ Nette\Forms\Form::$onSubmit[api:Nette\Forms\Form::Required]
→ Nette\Forms\Form::Required
Use fully qualified names only in the first mention. For subsequent links, use a simplified name:
[Form::setTranslator() |api:Nette\Forms\Form::setTranslator()]
→ Form::setTranslator()
Links to PHP Documentation
[php:substr]
→ substr
Source Code
A code block starts with ```lang
and ends with ```
. Supported languages are php
,
latte
, neon
, html
, css
, js
, and sql
. Always use tabs
for indentation.
```php
public function renderPage($id)
{
}
```
You can also specify the filename as ```php .{file: ArrayTest.php}
, and the code block will be rendered
this way:
public function renderPage($id)
{
}
Headings
Underline the top heading (page name) with asterisks (*
). Use equal signs (=
) to separate sections.
Underline headings first with equal signs (=
) and then with hyphens (-
):
MVC Applications & Presenters
*****************************
...
Link Creation
=============
...
Links in Templates
------------------
...
Boxes and Styles
Perex marked with class .[perex]
Note marked with class .[note]
Tip marked with class .[tip]
Caution marked with class .[caution]
Strong warning marked with class .[warning]
Version number .{data-version:2.4.10}
Classes should be written before the line they apply to:
.[perex]
This is the perex.
Please note that boxes like .[tip]
draw attention and therefore should be used for emphasizing important
information, not for less significant details. Use them sparingly.
Table of Contents
A table of contents (links in the right sidebar) is automatically generated for all pages exceeding 4,000 bytes in size. This
default behavior can be modified using the {{toc}}
meta tag. The text for the TOC is
taken directly from the headings by default, but it's possible to display different text using the .{toc}
modifier,
which is useful for longer headings.
Long and Intelligent Heading .{toc: A Different Text for TOC}
=============================================================
Meta Tags
- Set a custom page title (in
<title>
and breadcrumbs):{{title: Another name}}
- Redirect:
{{redirect: pla:cs}}
– see Links - Force
{{toc}}
or disable{{toc: no}}
the automatic table of contents (box with links to headings).