README.md - Issue 29325800: Noissue - Improve CMS usage documentation

Side by Side Diff: README.md

Issue 29325800: Noissue - Improve CMS usage documentation (Closed)

Patch Set: Addressed Wladimir's feedback Created Sept. 3, 2015, 1:02 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

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 for the given page name into the current language. Optionally a comment or

	269 description can be specified as well.
	Wladimir Palant 2015/09/03 13:37:37 What's the difference between comment and descript What's the difference between comment and description? As above, it should be explicitly noted that a comment is only something for translators. And maybe you should just call it "comment" everywhere (also in the Markdown section above)? kzar 2015/09/03 14:04:14 Well we seem to use both "comment" and "descriptio Show quoted text On 2015/09/03 13:37:37, Wladimir Palant wrote: > What's the difference between comment and description? As above, it should be > explicitly noted that a comment is only something for translators. And maybe you > should just call it "comment" everywhere (also in the Markdown section above)? Well we seem to use both "comment" and "description" in different places. For example the JSON structure (that we're stuck with) uses "description" and for the parameter here we use "comment". I thought it would be nice to clarify here that they're one in the same. I've adjusted the wording again, what do you think?
253 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is	270 * `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	271 a page name it will be converted into a link to the most appropriate page

255 language.	272 language.

256 * `toclist(html)`: extracts a list of headings from HTML code, this can be used	273 * `toclist(html)`: extracts a list of headings from HTML code, this can be used

257 to generate a table of contents.	274 to generate a table of contents.

258	275

	276 The following global functions can be used:

	277

	278 * `get_string(name, page=None)`: retrieves a string from a locale file.

	279 Unless a page is specified the locale file matching the name of the current

	280 page is used.

	281 * `get_page_content(page, locale=None)`: returns a dictionary of the content

	282 and params for the given page and locale. Locale defaults to the current one

	283 if not specified. Provided keys include:

	284

	285 ```

	286 ['head', 'body', 'available_locales', 'translation_ratio']

	287 ```
	Wladimir Palant 2015/09/03 13:37:37 Why have this as a Python list? "Provided keys inc Why have this as a Python list? "Provided keys include: `head`, `body`, `available_locales`, `translation_ratio`." kzar 2015/09/03 14:04:14 Done. Show quoted text On 2015/09/03 13:37:37, Wladimir Palant wrote: > Why have this as a Python list? "Provided keys include: `head`, `body`, > `available_locales`, `translation_ratio`." Done.
	288

259 ### Static files ###	289 ### Static files ###

260	290

261 Any files located in the `static` directory will be available on the server	291 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	292 unchanged. The file `static/css/foo.css` will be available under the URL

263 `/css/foo.css`.	293 `/css/foo.css`.

264	294

265 ### Templates ###	295 ### Templates ###

266	296

267 The templates specified in the `templates` directory specify the overall	297 The templates specified in the `templates` directory specify the overall

268 structure that is common for all pages. These templates should have the file	298 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	315 filter is invoked. For more information on Jinja2 filters see

286 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters).	316 [official documentation](http://jinja.pocoo.org/docs/dev/api/#writing-filters).

287	317

288 ### Custom functions and variables ###	318 ### Custom functions and variables ###

289	319

290 The `globals` directory can define custom Jinja2 globals which will be available	320 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	321 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	322 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	323 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.	324 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 »