mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update documentation for HTML templates style

Browse Source
This commit is contained in:
Guillaume Gomez 2023-03-06 11:17:02 +01:00
parent a776c17263
commit 511d2628c0
1 changed files with 14 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
src/librustdoc/html/templates/STYLE.md
View File

@ -10,28 +10,29 @@ similar to [Jinja2](jinjadoc) and [Django](djangodoc) templates, and also to [As
We want our rendered output to have as little unnecessary whitespace as We want our rendered output to have as little unnecessary whitespace as
possible, so that pages load quickly. To achieve that we use Tera's possible, so that pages load quickly. To achieve that we use Tera's
[whitespace control] features. At the end of most lines, we put an empty comment [whitespace control] features. By default, whitespace characters are removed
tag with the whitespace control characters: `{#- -#}`. This causes all around jinja tags (`{% %}` for example). At the end of most lines, we put an
whitespace between the end of the line and the beginning of the next, including empty comment tag: `{# #}`. This causes all whitespace between the end of the
indentation, to be omitted on render. Sometimes we want to preserve a single line and the beginning of the next, including indentation, to be omitted on
space. In those cases we put the space at the end of the line, followed by render. Sometimes we want to preserve a single space. In those cases we put the
`{# -#}`, which is a directive to remove following whitespace but not preceding. space at the end of the line, followed by `{#+ #}`, which is a directive to
We also use the whitespace control characters in most instances of tags with remove following whitespace but not preceding. We also use the whitespace
control flow, for example `{%- if foo -%}`. control characters in most instances of tags with control flow, for example
`{% if foo %}`.
[whitespace control]: https://tera.netlify.app/docs/#whitespace-control [whitespace control]: https://tera.netlify.app/docs/#whitespace-control
We want our templates to be readable, so we use indentation and newlines We want our templates to be readable, so we use indentation and newlines
liberally. We indent by four spaces after opening an HTML tag _or_ a Tera liberally. We indent by four spaces after opening an HTML tag _or_ a Jinja
tag. In most cases an HTML tag should be followed by a newline, but if the tag. In most cases an HTML tag should be followed by a newline, but if the
tag has simple contents and fits with its close tag on a single line, the tag has simple contents and fits with its close tag on a single line, the
contents don't necessarily need a new line. contents don't necessarily need a new line.
Tera templates support quite sophisticated control flow. To keep our templates Askama templates support quite sophisticated control flow. To keep our templates
simple and understandable, we use only a subset: `if` and `for`. In particular simple and understandable, we use only a subset: `if` and `for`. In particular
we avoid [assignments in the template logic](assignments) and [Tera we avoid [assignments in the template logic](assignments) and [Askama
macros](macros). This also may make things easier if we switch to a different macros](macros). This also may make things easier if we switch to a different
Jinja-style template system, like Askama, in the future. Jinja-style template system, like Askama, in the future.
[assignments]: https://tera.netlify.app/docs/#assignments [assignments]: https://djc.github.io/askama/template_syntax.html#assignments
[macros]: https://tera.netlify.app/docs/#macros [macros]: https://djc.github.io/askama/template_syntax.html#macros