Side by Side Diff: 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
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.
« docs/content/includes.md ('K')
|
« docs/content/locales.md ('k')
|
docs/content/settings.md » ('j')
|
no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')
| OLD | NEW |
|---|---|
| (Empty) | |
| 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. | |
| OLD | NEW |
« docs/content/includes.md ('K')
|
« docs/content/locales.md ('k')
|
docs/content/settings.md » ('j')
|
no next file with comments »
