src/librustdoc/html/templates/STYLE.md

   1 # Style for Templates
   2
   3 This directory has templates in the [Tera templating language](teradoc), which is very
   4 similar to [Jinja2](jinjadoc) and [Django](djangodoc) templates, and also to [Askama](askamadoc).
   5
   6 [teradoc]: https://tera.netlify.app/docs/#templates
   7 [jinjadoc]: https://jinja.palletsprojects.com/en/3.0.x/templates/
   8 [djangodoc]: https://docs.djangoproject.com/en/3.2/topics/templates/
   9 [askamadoc]: https://docs.rs/askama/0.10.5/askama/
  10
  11 We want our rendered output to have as little unnecessary whitespace as
  12 possible, so that pages load quickly. To achieve that we use Tera's
  13 [whitespace control] features. At the end of most lines, we put an empty comment
  14 tag with the whitespace control characters: `{#- -#}`. This causes all
  15 whitespace between the end of the line and the beginning of the next, including
  16 indentation, to be omitted on render. Sometimes we want to preserve a single
  17 space. In those cases we put the space at the end of the line, followed by
  18 `{# -#}`, which is a directive to remove following whitespace but not preceding.
  19 We also use the whitespace control characters in most instances of tags with
  20 control flow, for example `{%- if foo -%}`.
  21
  22 [whitespace control]: https://tera.netlify.app/docs/#whitespace-control
  23
  24 We want our templates to be readable, so we use indentation and newlines
  25 liberally. We indent by four spaces after opening an HTML tag _or_ a Tera
  26 tag. In most cases an HTML tag should be followed by a newline, but if the
  27 tag has simple contents and fits with its close tag on a single line, the
  28 contents don't necessarily need a new line.
  29
  30 Tera templates support quite sophisticated control flow. To keep our templates
  31 simple and understandable, we use only a subset: `if` and `for`. In particular
  32 we avoid [assignments in the template logic](assignments) and [Tera
  33 macros](macros). This also may make things easier if we switch to a different
  34 Jinja-style template system, like Askama, in the future.
  35
  36 [assignments]: https://tera.netlify.app/docs/#assignments
  37 [macros]: https://tera.netlify.app/docs/#macros