Side by Side Diff: README.md
Issue 29325800:
Noissue - Improve CMS usage documentation (Closed)
Patch Set: Addressed further feedback
Created Sept. 3, 2015, 2:01 p.m.
| Left: | ||
| Right: |
Use n/p to move between diff chunks;
N/P to move between comments.
« no previous file with comments
|
« no previous file
|
no next file »
|
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 |
|---|---|
| 1 # CMS # | 1 # CMS # |
| 2 | 2 |
| 3 We use this CMS for [adblockplus.org](https://github.com/adblockplus/web.adblock plus.org/) | 3 We use this CMS for [adblockplus.org](https://github.com/adblockplus/web.adblock plus.org/) |
| 4 and related websites. It converts a directory with content data into static | 4 and related websites. It converts a directory with content data into static |
| 5 files. You are free to use it for other projects but please keep in mind that we | 5 files. You are free to use it for other projects but please keep in mind that we |
| 6 make no stability guarantees whatsoever and might change functionality any time. | 6 make no stability guarantees whatsoever and might change functionality any time. |
| 7 | 7 |
| 8 ## How to use ## | 8 ## How to use ## |
| 9 | 9 |
| 10 ### Running the test server ### | 10 ### Running the test server ### |
| (...skipping 192 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
| 203 | 203 |
| 204 #### Markdown format (md) #### | 204 #### Markdown format (md) #### |
| 205 | 205 |
| 206 This format should normally be used, it allows the pages to be defined using the | 206 This format should normally be used, it allows the pages to be defined using the |
| 207 [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. Raw HTML | 207 [Markdown](http://daringfireball.net/projects/markdown/syntax) syntax. Raw HTML |
| 208 tags are allowed and can be used where Markdown syntax isn't sufficient. The | 208 tags are allowed and can be used where Markdown syntax isn't sufficient. The |
| 209 [Attribute Lists](http://pythonhosted.org/Markdown/extensions/attr_list.html) | 209 [Attribute Lists](http://pythonhosted.org/Markdown/extensions/attr_list.html) |
| 210 extension is active and allows specifying custom attributes for the generated | 210 extension is active and allows specifying custom attributes for the generated |
| 211 HTML tags. | 211 HTML tags. |
| 212 | 212 |
| 213 Localizable strings are retrieved from the locale file with the name matching | |
| 214 the page name. The following syntax can be used: `$foo$` inserts a string named | |
| 215 `foo` from the locale (no HTML code or Markdown syntax allowed in the string). | |
| 216 The syntax `$foo(foopage, http://example.com/)$` will work similarly but will | |
| 217 look for `<a>...</a>` blocks in the string: the first will be turned into a link | |
| 218 to the page `foopage`, the second will become a link to `http://example.com/`. | |
| 219 | |
| 220 Any content between `<head>` and `</head>` tags will be inserted into the head | 213 Any content between `<head>` and `</head>` tags will be inserted into the head |
| 221 of the generated web page, this is meant for styles, scripts and the like. | 214 of the generated web page, this is meant for styles, scripts and the like. |
| 222 Other pages should be linked by using their name as link target (relative links) , | 215 Other pages should be linked by using their name as link target (relative links) , |
| 223 these links will be resolved to point to the most appropriate page language. | 216 these links will be resolved to point to the most appropriate page language. |
| 224 Embedding localizable images works the same, use the image name as image source. | 217 Embedding localizable images works the same, use the image name as image source. |
| 225 | 218 |
| 219 Localizable strings can be specified inline with the following syntax: | |
| 220 | |
| 221 {{string_name String contents in default language}} | |
| 222 | |
| 223 Try to give the string a descriptive name as it will help translators. | |
| 224 Optionally you can add a description for strings as well to provide even more | |
| 225 context: | |
| 226 | |
| 227 {{string_name[The string description] String contents}} | |
| 228 | |
| 229 _Note: String names and descriptions have no effect on the generated page, | |
| 230 assuming string name is unique to the page. The name and description are just | |
| 231 used to provide translators with additional context about the string._ | |
| 232 | |
| 233 Finally if you find yourself using the same string multiple times in a page | |
| 234 you can reduce duplication by simply omitting the description and contents | |
| 235 after the first use. For example: | |
| 236 | |
| 237 {{title[Title of the page] Adblock Plus - Home}} | |
| 238 {{title}} | |
| 239 | |
| 226 #### Raw HTML format (html) #### | 240 #### Raw HTML format (html) #### |
| 227 | 241 |
| 228 This format is similar to the Markdown format but uses regular HTML syntax. | 242 This format is similar to the Markdown format but uses regular HTML syntax. |
| 229 No processing is performed beyond inserting localized strings and resolving | 243 No processing is performed beyond inserting localized strings and resolving |
| 230 links to pages and images. This format is mainly meant for legacy content. | 244 links to pages and images. This format is mainly meant for legacy content. |
| 245 The syntax for localizable strings documented above can be used as with | |
| 246 Markdown. | |
| 231 | 247 |
| 232 #### Jinja2 format (tmpl) #### | 248 #### Jinja2 format (tmpl) #### |
| 233 | 249 |
| 234 Complicated pages can be defined using the | 250 Complicated pages can be defined using the |
| 235 [Jinja2 template format](http://jinja.pocoo.org/docs/templates/). Automatic | 251 [Jinja2 template format](http://jinja.pocoo.org/docs/templates/). Automatic |
| 236 escaping is active so by default values inserted into the page cannot contain | 252 escaping is active so by default values inserted into the page cannot contain |
| 237 any HTML code. Any content between `<head>` and `</head>` tags will be inserted | 253 any HTML code. Any content between `<head>` and `</head>` tags will be inserted |
| 238 into the head of the generated web page, everything else defined the content of | 254 into the head of the generated web page, everything else defined the content of |
| 239 the page. | 255 the page. |
| 240 | 256 |
| 241 The following variables can be used: | 257 The following variables can be used: |
| 242 | 258 |
| 243 * `page`: The page name | 259 * `page`: The page name |
| 244 * `config`: Contents of the `settings.ini` file in this repository (a | 260 * `config`: Contents of the `settings.ini` file in this repository (a |
| 245 [configparser object](http://docs.python.org/2/library/configparser.html)) | 261 [configparser object](http://docs.python.org/2/library/configparser.html)) |
| 246 * `locale`: Locale code of the page language | 262 * `locale`: Locale code of the page language |
| 247 * `available_locales`: Locale codes of all languages available for this page | 263 * `available_locales`: Locale codes of all languages available for this page |
| 248 | 264 |
| 249 Following custom filters can be used: | 265 Following custom filters can be used: |
| 250 | 266 |
| 251 * `translate(string, locale=None)`: retrieves a string from a locale file. | 267 * `translate(default, name, comment=None)`: translates the given default string |
| 252 Unless a locale is specified the locale file matching the page name is used. | 268 and string name for the current page and locale. The string name should be |
| 269 unique for the page but otherwise is only seen by the translators. Optionally | |
| 270 a comment (description) can be specified to help provide the translators with | |
| 271 additional context. | |
| 253 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is | 272 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is |
| 254 a page name it will be converted into a link to the most appropriate page | 273 a page name it will be converted into a link to the most appropriate page |
| 255 language. | 274 language. |
| 256 * `toclist(html)`: extracts a list of headings from HTML code, this can be used | 275 * `toclist(html)`: extracts a list of headings from HTML code, this can be used |
| 257 to generate a table of contents. | 276 to generate a table of contents. |
| 258 | 277 |
| 278 The following global functions can be used: | |
| 279 | |
| 280 * `get_string(name, page=None)`: retrieves a string from a locale file. | |
| 281 Unless a page is specified the locale file matching the name of the current | |
| 282 page is used. | |
| 283 * `get_page_content(page, locale=None)`: returns a dictionary of the content | |
| 284 and params for the given page and locale. Locale defaults to the current one | |
| 285 if not specified. Provided keys include `head`, `body`, `available_locales` | |
| 286 and `translation_ratio`. | |
| 287 | |
| 259 ### Static files ### | 288 ### Static files ### |
| 260 | 289 |
| 261 Any files located in the `static` directory will be available on the server | 290 Any files located in the `static` directory will be available on the server |
| 262 unchanged. The file `static/css/foo.css` will be available under the URL | 291 unchanged. The file `static/css/foo.css` will be available under the URL |
| 263 `/css/foo.css`. | 292 `/css/foo.css`. |
| 264 | 293 |
| 265 ### Templates ### | 294 ### Templates ### |
| 266 | 295 |
| 267 The templates specified in the `templates` directory specify the overall | 296 The templates specified in the `templates` directory specify the overall |
| 268 structure that is common for all pages. These templates should have the file | 297 structure that is common for all pages. These templates should have the file |
| (...skipping 16 matching lines...) Expand all Loading... | |
| 285 filter is invoked. For more information on Jinja2 filters see | 314 filter is invoked. For more information on Jinja2 filters see |
| 286 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters). | 315 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters). |
| 287 | 316 |
| 288 ### Custom functions and variables ### | 317 ### Custom functions and variables ### |
| 289 | 318 |
| 290 The `globals` directory can define custom Jinja2 globals which will be available | 319 The `globals` directory can define custom Jinja2 globals which will be available |
| 291 in all Jinja2 templates. Typically, this is used for custom functions. The file | 320 in all Jinja2 templates. Typically, this is used for custom functions. The file |
| 292 name should match the name of the function or variable to be defined, and export | 321 name should match the name of the function or variable to be defined, and export |
| 293 a variable with that name. E.g. `globals/myfunction.py` can define a function | 322 a variable with that name. E.g. `globals/myfunction.py` can define a function |
| 294 called `myfunction` that will become available to all Jinja2 templates. | 323 called `myfunction` that will become available to all Jinja2 templates. |
| OLD | NEW |
« no previous file with comments
|
« no previous file
|
no next file »
|
no next file with comments »
