Side by Side Diff: docs/structure/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:
Created Dec. 4, 2017, 9:59 a.m.
| Left: | ||
| Right: |
Use n/p to move between diff chunks;
N/P to move between comments.
« README.md ('K')
|
« docs/structure/locales.md ('k')
|
docs/structure/settings.md » ('j')
|
docs/structure/static.md » ('J')
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 The following tag inserts an include file into the page (can be in a different | |
| 26 format): | |
| 27 | |
| 28 <? include foo ?> | |
| 29 | |
| 30 Include files should be placed into the `includes` directory of the repository. | |
| 31 In the case above the contents of `includes/foo.md` or `includes/foo.tmpl` will | |
| 32 be inserted (whichever is present). | |
| 33 | |
| 34 ## Markdown format (md) ## | |
| 35 | |
| 36 This format should normally be used, it allows the pages to be defined using the | |
| 37 [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. Raw HTML | |
| 38 tags are allowed and can be used where Markdown syntax isn't sufficient. The | |
| 39 [Python-Markdown Extra](https://pythonhosted.org/Markdown/extensions/extra.html) | |
| 40 extension is active and allows specifying custom attributes for the generated | |
| 41 HTML tags, HTML block elements that contain Markdown and more. | |
| 42 | |
| 43 Any content between `<head>` and `</head>` tags will be inserted into the head | |
| 44 of the generated web page, this is meant for styles, scripts and the like. | |
| 45 Other pages should be linked by using their name as link target (relative links) , | |
| 46 these links will be resolved to point to the most appropriate page language. | |
| 47 Embedding localizable images works the same, use the image name as image source. | |
| 48 | |
| 49 Localizable strings can be specified inline with the following syntax: | |
| 50 | |
| 51 {{string_name String contents in default language}} | |
| 52 | |
| 53 Try to give the string a descriptive name as it will help translators. | |
| 54 Optionally you can add a description for strings as well to provide even more | |
| 55 context: | |
| 56 | |
| 57 {{string_name[The string description] String contents}} | |
| 58 | |
| 59 _Note: String names and descriptions have no effect on the generated page, | |
| 60 assuming string name is unique to the page. The name and description are just | |
| 61 used to provide translators with additional context about the string._ | |
| 62 | |
| 63 Finally if you find yourself using the same string multiple times in a page | |
| 64 you can reduce duplication by simply omitting the description and contents | |
| 65 after the first use. For example: | |
| 66 | |
| 67 {{title[Title of the page] Adblock Plus - Home}} | |
| 68 {{title}} | |
| 69 | |
| 70 ## Raw HTML format (html) ## | |
| 71 | |
| 72 This format is similar to the Markdown format but uses regular HTML syntax. | |
| 73 No processing is performed beyond inserting localized strings and resolving | |
| 74 links to pages and images. This format is mainly meant for legacy content. | |
| 75 The syntax for localizable strings documented above can be used as with | |
| 76 Markdown. | |
| 77 | |
| 78 ## Jinja2 format (tmpl) ## | |
| 79 | |
| 80 Complicated pages can be defined using the | |
| 81 [Jinja2 template format](http://jinja.pocoo.org/docs/templates/). Automatic | |
| 82 escaping is active so by default values inserted into the page cannot contain | |
| 83 any HTML code. Any content between `<head>` and `</head>` tags will be inserted | |
| 84 into the head of the generated web page, everything else defined the content of | |
| 85 the page. | |
| 86 | |
| 87 The following variables can be used: | |
| 88 | |
| 89 * `page`: The page name | |
| 90 * `config`: Contents of the `settings.ini` file in this repository (a | |
| 91 [configparser object](http://docs.python.org/2/library/configparser.html)) | |
| 92 * `locale`: Locale code of the page language | |
| 93 * `available_locales`: Locale codes of all languages available for this page | |
| 94 | |
| 95 Following custom filters can be used: | |
| 96 | |
| 97 * `translate(default, name, comment=None)`: translates the given default string | |
| 98 and string name for the current page and locale. The string name should be | |
| 99 unique for the page but otherwise is only seen by the translators. Optionally | |
| 100 a comment (description) can be specified to help provide the translators with | |
| 101 additional context. | |
| 102 * `linkify(url, locale=None, **attrs)`: generates an `<a href="...">` tag for | |
| 103 the URL. If the URL is a page name it will be converted into a link to the | |
| 104 most appropriate page language. The language used can also be specified | |
| 105 manually with the locale parameter. Any further keyword arguments passed | |
| 106 are turned into additional HTML attributes for the tag. | |
| 107 * `toclist(html)`: extracts a list of headings from HTML code, this can be used | |
| 108 to generate a table of contents. | |
| 109 | |
| 110 The following global functions can be used: | |
| 111 | |
| 112 * `get_string(name, page=None)`: retrieves a string from a locale file. | |
| 113 Unless a page is specified the locale file matching the name of the current | |
| 114 page is used. | |
| 115 * `get_page_content(page, locale=None)`: returns a dictionary of the content | |
| 116 and params for the given page and locale. Locale defaults to the current one | |
| 117 if not specified. Provided keys include `head`, `body`, `available_locales` | |
| 118 and `translation_ratio`. | |
| OLD | NEW |
« README.md ('K')
|
« docs/structure/locales.md ('k')
|
docs/structure/settings.md » ('j')
|
docs/structure/static.md » ('J')
