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

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

LEFT	RIGHT
(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.

LEFT	RIGHT