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: Created Sept. 3, 2015, 11:54 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
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 183 matching lines...) Expand 10 before \| Expand all \| Expand 10 after Loading...
194	194

195 The following tag inserts an include file into the page (can be in a different	195 The following tag inserts an include file into the page (can be in a different

196 format):	196 format):

197	197

198 <? include foo ?>	198 <? include foo ?>

199	199

200 Include files should be placed into the `includes` directory of the repository.	200 Include files should be placed into the `includes` directory of the repository.

201 In the case above the contents of `includes/foo.md` or `includes/foo.tmpl` will	201 In the case above the contents of `includes/foo.md` or `includes/foo.tmpl` will

202 be inserted (whichever is present).	202 be inserted (whichever is present).

203	203

	204 When writing content that needs to be translated into the different supported

	205 languages you can use the following syntax:

	206

	207 {{string_name String contents in default language}}

	208

	209 Try to give the string a descriptive name as it will help translators.

	210 Optionally you can add a description for strings as well to provide even more

	211 context:

	212

	213 {{string_name[The string description] String contents}}
	Wladimir Palant 2015/09/03 12:15:26 You need to point out explicitly that neither the You need to point out explicitly that neither the string name nor description have any effect on the generated markup - they are merely context information visible to translators. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > You need to point out explicitly that neither the string name nor description > have any effect on the generated markup - they are merely context information > visible to translators. Done.
	214

	215 Finally if you find yourself using the same string multiple times in a page

	216 you can reduce duplication by simply omitting the description and contents

	217 after the first use. For example:

	218

	219 {{title[Title of the page] Adblock Plus - Home}}

	220 {{title}}

	221

	222 _Note: For Jinja2 templates this syntax does not work, you will need to use the

	223 custom Jinja2 filters and global functions as documented below._
	Wladimir Palant 2015/09/03 12:15:26 This section belongs under "Markdown format" - tha This section belongs under "Markdown format" - that's how Markdown files are being localized. You can add a note under "Raw html" saying that the localization approach there is identical to Markdown (it sort of says so already). kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > This section belongs under "Markdown format" - that's how Markdown files are > being localized. You can add a note under "Raw html" saying that the > localization approach there is identical to Markdown (it sort of says so > already). Done.
	224

204 #### Markdown format (md) ####	225 #### Markdown format (md) ####

205	226

206 This format should normally be used, it allows the pages to be defined using the	227 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	228 [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	229 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)	230 [Attribute Lists](http://pythonhosted.org/Markdown/extensions/attr_list.html)

210 extension is active and allows specifying custom attributes for the generated	231 extension is active and allows specifying custom attributes for the generated

211 HTML tags.	232 HTML tags.

212	233

213 Localizable strings are retrieved from the locale file with the name matching	234 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	235 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).	236 `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	237 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	238 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/`.	239 to the page `foopage`, the second will become a link to `http://example.com/`.
	Wladimir Palant 2015/09/03 12:15:26 This section is outdated and needs to be merged wi This section is outdated and needs to be merged with the text above. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > This section is outdated and needs to be merged with the text above. Done.
219	240

220 Any content between `<head>` and `</head>` tags will be inserted into the head	241 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.	242 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) ,	243 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.	244 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.	245 Embedding localizable images works the same, use the image name as image source.

225	246

226 #### Raw HTML format (html) ####	247 #### Raw HTML format (html) ####

227	248

228 This format is similar to the Markdown format but uses regular HTML syntax.	249 This format is similar to the Markdown format but uses regular HTML syntax.

(...skipping 12 matching lines...) Expand all Loading...
241 The following variables can be used:	262 The following variables can be used:

242	263

243 * `page`: The page name	264 * `page`: The page name

244 * `config`: Contents of the `settings.ini` file in this repository (a	265 * `config`: Contents of the `settings.ini` file in this repository (a

245 [configparser object](http://docs.python.org/2/library/configparser.html))	266 [configparser object](http://docs.python.org/2/library/configparser.html))

246 * `locale`: Locale code of the page language	267 * `locale`: Locale code of the page language

247 * `available_locales`: Locale codes of all languages available for this page	268 * `available_locales`: Locale codes of all languages available for this page

248	269

249 Following custom filters can be used:	270 Following custom filters can be used:

250	271

251 * `translate(string, locale=None)`: retrieves a string from a locale file.	272 * `translate(string, name, comment=None)`: retrieves a string from a locale file

252 Unless a locale is specified the locale file matching the page name is used.	273 for the given page name in the current language. Optionally a comment or

	274 description can be specified as well.
	Wladimir Palant 2015/09/03 12:15:26 First parameter isn't string any more, it's defaul First parameter isn't string any more, it's default - you should point out what it means. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > First parameter isn't string any more, it's default - you should point out what > it means. Done.
253 * `linkify(url)`: generates an `<a href="...">` tag for the URL. If the URL is	275 * `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	276 a page name it will be converted into a link to the most appropriate page

255 language.	277 language.

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

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

258	280

	281 The following global functions can be used:

	282

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

	284 Unless a locale is specified the locale file matching the page name is used.
	Wladimir Palant 2015/09/03 12:15:26 I think you meant: "Unless a page is specified the I think you meant: "Unless a page is specified the locale file matching the name of the current page is used." kzar 2015/09/03 13:05:32 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > I think you meant: "Unless a page is specified the locale file matching the name > of the current page is used." Done.
	285 * `get_page_content(page, locale=None)`: returns a dictionary of the content

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

	287 if not specified. Provided keys include:

	288

	289 ```

	290 ['localized_string_callback', 'body', 'templatedata', 'available_locales',

	291 'title', 'locale', 'head', 'source', 'localedata', 'template', 'defaultlocale',

	292 'pagedata', 'translation_ratio', 'config', 'page']
	Wladimir Palant 2015/09/03 12:15:26 Please don't list everything returned. In particul Please don't list everything returned. In particular, things meant for internal use and the ones identical to the current page are irrelevant. It's really: head, body, available_locales, translation_ratio. kzar 2015/09/03 13:05:33 Done. Show quoted text On 2015/09/03 12:15:26, Wladimir Palant wrote: > Please don't list everything returned. In particular, things meant for internal > use and the ones identical to the current page are irrelevant. It's really: > head, body, available_locales, translation_ratio. Done.
	293 ```

	294

259 ### Static files ###	295 ### Static files ###

260	296

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

263 `/css/foo.css`.	299 `/css/foo.css`.

264	300

265 ### Templates ###	301 ### Templates ###

266	302

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

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

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

287	323

288 ### Custom functions and variables ###	324 ### Custom functions and variables ###

289	325

290 The `globals` directory can define custom Jinja2 globals which will be available	326 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	327 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	328 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	329 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.	330 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 »