docs/structure/pages.md - Issue 29628724: Issue 5521 - Restructure CMS documentation to make it easier to use and extend

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.

Jump to:

View unified diff | Download patch

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')