Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

Delta Between Two Patch Sets: docs/content/pages.md

Issue 29628724: Issue 5521 - Restructure CMS documentation to make it easier to use and extend (Closed) Base URL: https://hg.adblockplus.org/cms
Left Patch Set: Created Dec. 4, 2017, 9:59 a.m.
Right Patch Set: Add initial API docs Created Dec. 13, 2017, 11:08 a.m.
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments.
Jump to:
Right: Side by side diff | Download
LEFTRIGHT
(no file at all)
1 # Pages #
2
3 The pages are defined in the `pages` directory. The file extension defines the
4 format in which a page is specified and won't be visible on the web server.
5 The page name is prepended by the locale code in the URL, e.g. `pages/foo.md`
6 can be available under the URLs `/en/foo` and `/de/foo` (the English and German
7 versions respectively). Regardless of the format, a page can define a number of
8 settings using the following format:
9
10 setting = value
11
12 Note that the settings have to placed at the beginning of the file, before the
13 actual content. The following settings can be changed:
14
15 * `template`: This defines the template to be used for this page (without the
16 file extension). By default the `default` template is used for all pages.
17 * `title`: The locale string to be used as page title. By default the `title`
18 string is used.
19 * `noheading`: Setting this to any value will make sure no heading is displayed.
20 By default a `<h1>` tag with the page title is added above the content.
21 * `notoc`: Setting this to any value will prevent a table of contents from being
22 generated. By default a table of contents is always generated if the page
23 contains any headers with an `id` attribute.
24
25 For information on using includes on pages, read the guide on
26 [Include files](includes.md)
27
28 ## Markdown format (md) ##
29
30 This format should normally be used, it allows the pages to be defined using the
31 [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. Raw HTML
32 tags are allowed and can be used where Markdown syntax isn't sufficient. The
33 [Python-Markdown Extra](https://pythonhosted.org/Markdown/extensions/extra.html)
34 extension is active and allows specifying custom attributes for the generated
35 HTML tags, HTML block elements that contain Markdown and more.
36
37 Any content between `<head>` and `</head>` tags will be inserted into the head
38 of the generated web page, this is meant for styles, scripts and the like.
39 Other pages should be linked by using their name as link target (relative links) ,
40 these links will be resolved to point to the most appropriate page language.
41 Embedding localizable images works the same, use the image name as image source.
42
43 Localizable strings can be specified inline with the following syntax:
44
45 {{string_name String contents in default language}}
46
47 Try to give the string a descriptive name as it will help translators.
48 Optionally you can add a description for strings as well to provide even more
49 context:
50
51 {{string_name[The string description] String contents}}
52
53 _Note: String names and descriptions have no effect on the generated page,
54 assuming string name is unique to the page. The name and description are just
55 used to provide translators with additional context about the string._
56
57 Finally if you find yourself using the same string multiple times in a page
58 you can reduce duplication by simply omitting the description and contents
59 after the first use. For example:
60
61 {{title[Title of the page] Adblock Plus - Home}}
62 {{title}}
63
64 ## Raw HTML format (html) ##
65
66 This format is similar to the Markdown format but uses regular HTML syntax.
67 No processing is performed beyond inserting localized strings and resolving
68 links to pages and images. This format is mainly meant for legacy content.
69 The syntax for localizable strings documented above can be used as with
70 Markdown.
71
72 ## Jinja2 format (tmpl) ##
73
74 Complicated pages can be defined using the
75 [Jinja2 template format](http://jinja.pocoo.org/docs/templates/). Automatic
76 escaping is active so by default values inserted into the page cannot contain
77 any HTML code. Any content between `<head>` and `</head>` tags will be inserted
78 into the head of the generated web page, everything else defined the content of
79 the page.
80
81 Read the API documentation on [variables](../api/variables.md),
82 [global functions](../api/functions.md), and [custom filters](../api/filters.md)
83 that can be used on pages.
LEFTRIGHT

Powered by Google App Engine
This is Rietveld