Unified 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.
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')
Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')
Expand Comments ('e') | Collapse Comments ('c') | Hide Comments ('s')
| Index: docs/structure/pages.md |
| =================================================================== |
| new file mode 100644 |
| --- /dev/null |
| +++ b/docs/structure/pages.md |
| @@ -0,0 +1,118 @@ |
| +# Pages # |
| + |
| +The pages are defined in the `pages` directory. The file extension defines the |
| +format in which a page is specified and won't be visible on the web server. |
| +The page name is prepended by the locale code in the URL, e.g. `pages/foo.md` |
| +can be available under the URLs `/en/foo` and `/de/foo` (the English and German |
| +versions respectively). Regardless of the format, a page can define a number of |
| +settings using the following format: |
| + |
| + setting = value |
| + |
| +Note that the settings have to placed at the beginning of the file, before the |
| +actual content. The following settings can be changed: |
| + |
| +* `template`: This defines the template to be used for this page (without the |
| + file extension). By default the `default` template is used for all pages. |
| +* `title`: The locale string to be used as page title. By default the `title` |
| + string is used. |
| +* `noheading`: Setting this to any value will make sure no heading is displayed. |
| + By default a `<h1>` tag with the page title is added above the content. |
| +* `notoc`: Setting this to any value will prevent a table of contents from being |
| + generated. By default a table of contents is always generated if the page |
| + contains any headers with an `id` attribute. |
| + |
| +The following tag inserts an include file into the page (can be in a different |
| +format): |
| + |
| + <? include foo ?> |
| + |
| +Include files should be placed into the `includes` directory of the repository. |
| +In the case above the contents of `includes/foo.md` or `includes/foo.tmpl` will |
| +be inserted (whichever is present). |
| + |
| +## Markdown format (md) ## |
| + |
| +This format should normally be used, it allows the pages to be defined using the |
| +[Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. Raw HTML |
| +tags are allowed and can be used where Markdown syntax isn't sufficient. The |
| +[Python-Markdown Extra](https://pythonhosted.org/Markdown/extensions/extra.html) |
| +extension is active and allows specifying custom attributes for the generated |
| +HTML tags, HTML block elements that contain Markdown and more. |
| + |
| +Any content between `<head>` and `</head>` tags will be inserted into the head |
| +of the generated web page, this is meant for styles, scripts and the like. |
| +Other pages should be linked by using their name as link target (relative links), |
| +these links will be resolved to point to the most appropriate page language. |
| +Embedding localizable images works the same, use the image name as image source. |
| + |
| +Localizable strings can be specified inline with the following syntax: |
| + |
| + {{string_name String contents in default language}} |
| + |
| +Try to give the string a descriptive name as it will help translators. |
| +Optionally you can add a description for strings as well to provide even more |
| +context: |
| + |
| + {{string_name[The string description] String contents}} |
| + |
| +_Note: String names and descriptions have no effect on the generated page, |
| +assuming string name is unique to the page. The name and description are just |
| +used to provide translators with additional context about the string._ |
| + |
| +Finally if you find yourself using the same string multiple times in a page |
| +you can reduce duplication by simply omitting the description and contents |
| +after the first use. For example: |
| + |
| + {{title[Title of the page] Adblock Plus - Home}} |
| + {{title}} |
| + |
| +## Raw HTML format (html) ## |
| + |
| +This format is similar to the Markdown format but uses regular HTML syntax. |
| +No processing is performed beyond inserting localized strings and resolving |
| +links to pages and images. This format is mainly meant for legacy content. |
| +The syntax for localizable strings documented above can be used as with |
| +Markdown. |
| + |
| +## Jinja2 format (tmpl) ## |
| + |
| +Complicated pages can be defined using the |
| +[Jinja2 template format](http://jinja.pocoo.org/docs/templates/). Automatic |
| +escaping is active so by default values inserted into the page cannot contain |
| +any HTML code. Any content between `<head>` and `</head>` tags will be inserted |
| +into the head of the generated web page, everything else defined the content of |
| +the page. |
| + |
| +The following variables can be used: |
| + |
| +* `page`: The page name |
| +* `config`: Contents of the `settings.ini` file in this repository (a |
| + [configparser object](http://docs.python.org/2/library/configparser.html)) |
| +* `locale`: Locale code of the page language |
| +* `available_locales`: Locale codes of all languages available for this page |
| + |
| +Following custom filters can be used: |
| + |
| +* `translate(default, name, comment=None)`: translates the given default string |
| + and string name for the current page and locale. The string name should be |
| + unique for the page but otherwise is only seen by the translators. Optionally |
| + a comment (description) can be specified to help provide the translators with |
| + additional context. |
| +* `linkify(url, locale=None, **attrs)`: generates an `<a href="...">` tag for |
| + the URL. If the URL is a page name it will be converted into a link to the |
| + most appropriate page language. The language used can also be specified |
| + manually with the locale parameter. Any further keyword arguments passed |
| + are turned into additional HTML attributes for the tag. |
| +* `toclist(html)`: extracts a list of headings from HTML code, this can be used |
| + to generate a table of contents. |
| + |
| +The following global functions can be used: |
| + |
| +* `get_string(name, page=None)`: retrieves a string from a locale file. |
| + Unless a page is specified the locale file matching the name of the current |
| + page is used. |
| +* `get_page_content(page, locale=None)`: returns a dictionary of the content |
| + and params for the given page and locale. Locale defaults to the current one |
| + if not specified. Provided keys include `head`, `body`, `available_locales` |
| + and `translation_ratio`. |
« README.md ('K')
|
« docs/structure/locales.md ('k')
|
docs/structure/settings.md » ('j')
|
docs/structure/static.md » ('J')
