You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

overview.md 5.5KB

6 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149
  1. +++
  2. title = "Overview"
  3. weight = 10
  4. +++
  5. Gutenberg uses the [Tera](https://tera.netlify.com) template engine and is very similar
  6. to Jinja2, Liquid or Twig.
  7. As this documentation will only talk about how templates work in Gutenberg, please read
  8. the [Tera template documentation](https://tera.netlify.com/docs/templates/) if you want
  9. to learn more about it first.
  10. All templates live in the `templates` directory. If you are not sure what variables are available in a template, you can just stick `{{ __tera_context }}` in it
  11. to print the whole context.
  12. A few variables are available on all templates minus RSS and sitemap:
  13. - `config`: the [configuration](./documentation/getting-started/configuration.md) without any modifications
  14. - `current_path`: the path (full URL without the `base_url`) of the current page, never starting with a `/`
  15. - `current_url`: the full URL for that page
  16. ## Standard Templates
  17. By default, Gutenberg will look for three templates: `index.html`, which is applied
  18. to the site homepage; `section.html`, which is applied to all sections (any HTML
  19. page generated by creating a directory within your `content` directory); and
  20. `page.html`, which is applied to all pages (any HTML page generated by creating a
  21. `.md` file within your `content` directory).
  22. The homepage is always a section (regardless of whether it contains other pages).
  23. Thus, the `index.html` and `section.html` templates both have access to the
  24. section variables. The `page.html` template has access to the page variables.
  25. The page and section variables are described in more detail in the next section of this documentation.
  26. ## Built-in Templates
  27. Gutenberg comes with three built-in templates: `rss.xml`, `sitemap.xml`, and
  28. `robots.txt` (each described in their own section of this documentation).
  29. Additionally, themes can add their own templates, which will be applied if not
  30. overridden. You can override built-in or theme templates by creating a template with
  31. same name in the correct path. For example, you can override the RSS template by
  32. creating a `templates/rss.xml` file.
  33. ## Custom Templates
  34. In addition to the standard `index.html`, `section.html`, and `page.html` templates,
  35. you may also create custom templates by creating a `.html` file in the `templates`
  36. directory. These custom templates will not be used by default. Instead, the custom template will _only_ be used if you apply it by setting the `template` front-matter variable to the path for that template (or if you `include` it in another template that is applied). For example, if you created a custom template for your site's About page called `about.html`, you could apply it to your `about.md` page by including the following front matter in your `about.md` page:
  37. ```md
  38. +++
  39. title = "About Us"
  40. template = "about.html"
  41. +++
  42. ```
  43. Custom templates are not required to live at the root of your `templates` directory.
  44. For example, `product_pages/with_pictures.html` is a valid template.
  45. ## Built-in filters
  46. Gutenberg adds a few filters, in addition of the ones already present in Tera.
  47. ### markdown
  48. Converts the given variable to HTML using Markdown. This doesn't apply any of the
  49. features that Gutenberg adds to Markdown: internal links, shortcodes etc won't work.
  50. By default, the filter will wrap all text into a paragraph. To disable that, you can
  51. pass `true` to the inline argument:
  52. ```jinja2
  53. {{ some_text | markdown(inline=true) }}
  54. ```
  55. ### base64_encode
  56. Encode the variable to base64.
  57. ### base64_decode
  58. Decode the variable from base64.
  59. ## Built-in global functions
  60. Gutenberg adds a few global functions to Tera in order to make it easier to develop complex sites.
  61. ### `get_page`
  62. Takes a path to a `.md` file and returns the associated page
  63. ```jinja2
  64. {% set page = get_page(path="blog/page2.md") %}
  65. ```
  66. ### `get_section`
  67. Takes a path to a `_index.md` file and returns the associated section
  68. ```jinja2
  69. {% set section = get_section(path="blog/_index.md") %}
  70. ```
  71. ### ` get_url`
  72. Gets the permalink for the given path.
  73. If the path starts with `./`, it will be understood as an internal
  74. link like the ones used in markdown.
  75. ```jinja2
  76. {% set url = get_url(path="./blog/_index.md") %}
  77. ```
  78. This can also be used to get the permalinks for static assets for example if
  79. we want to link to the file that is located at `static/css/app.css`:
  80. ```jinja2
  81. {{/* get_url(path="css/app.css") */}}
  82. ```
  83. For assets it is reccommended that you pass `trailing_slash=false` to the `get_url` function. This prevents errors
  84. when dealing with certain hosting providers. An example is:
  85. ```jinja2
  86. {{/* get_url(path="css/app.css", trailing_slash=false) */}}
  87. ```
  88. In the case of non-internal links, you can also add a cachebust of the format `?t=1290192` at the end of a URL
  89. by passing `cachebust=true` to the `get_url` function.
  90. ### `get_taxonomy_url`
  91. Gets the permalink for the taxonomy item found.
  92. ```jinja2
  93. {% set url = get_taxonomy_url(kind="categories", name=page.taxonomies.category) %}
  94. ```
  95. The `name` will almost come from a variable but in case you want to do it manually,
  96. the value should be the same as the one in the front-matter, not the slugified version.
  97. ### `get_taxonomy`
  98. Gets the whole taxonomy of a specific kind.
  99. ```jinja2
  100. {% set categories = get_taxonomy_url(kind="categories") %}
  101. ```
  102. ### `trans`
  103. Gets the translation of the given `key`, for the `default_language` or the `language given
  104. ```jinja2
  105. {{/* trans(key="title") */}}
  106. {{/* trans(key="title", lang="fr") */}}
  107. ```
  108. ### `resize_image`
  109. Resizes an image file.
  110. Pease refer to [_Content / Image Processing_](./documentation/content/image-processing/index.md) for complete documentation.