Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code

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.
Jump to:
View unified diff | Download patch
« 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') | Show Comments Hide Comments ('s')
OLDNEW
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
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
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.
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld