From: R. Steve McKown Date: Tue, 9 Aug 2011 02:14:40 +0000 (-0600) Subject: Merge branch 'upstream' X-Git-Url: https://oss.titaniummirror.com/gitweb?a=commitdiff_plain;h=b5bc4ffdfbaa76db7cd4cdeb078097ec17024f6b;hp=c6d30c7f18e835e0b99032d01b1f8acd7f077ec6;p=webber.git Merge branch 'upstream' Conflicts: in/sitemap.md plugins/read_markdown.py --- diff --git a/Makefile b/Makefile index 2e69fb2..4529496 100644 --- a/Makefile +++ b/Makefile @@ -5,6 +5,13 @@ all: webber.conf profile: ./webber --profile +lint: + pylint \ + --include-ids=y \ + --reports=n \ + --disable-msg=W0312,C0103 \ + webber.py plugins + clean: rm -f *.pyc plugins/*.pyc diff --git a/in/commandline.md b/in/commandline.md index 0aca797..6a35634 100644 --- a/in/commandline.md +++ b/in/commandline.md @@ -1,14 +1,19 @@ title: Command line options linktitle: Cmdline parent: Configuration +lang: en ctime: 2009-06-24 +mtime: 2009-06-26 -= Help = +Note that command line options can also be specified via [[configuration]]. -As usualy, you can get command line help with "`-h`" or "`--help`": += Invoke help = +As usual, you can get command line help with "`-h`" or "`--help`": + + $ webber/webber --help usage: webber [options] - + options: -h, --help show this help message and exit -i DIR, --in=DIR input directory @@ -49,5 +54,3 @@ to increase even more. With "`-k`" or "`--keepgoing`" you can tell webber to ignore errors in one page and continue with the next page. - - diff --git a/in/configuration.md b/in/configuration.md index ed5648f..25f6454 100644 --- a/in/configuration.md +++ b/in/configuration.md @@ -1,80 +1,154 @@ title: Configuration parent: Webber +lang: en ctime: 2009-06-24 +mtime: 2010-07-06 +change: enhanced, fixed and clarified -Configuration happens either the [[commandline]] or -via the configuration file (described below). All Configurations are -[[inherited|inheritance]] and or overwritable on a per-directory and -per-file basis. +Configuration happens either via [[commandline]] or with the +configuration file (described below). All configurations are subject +to [[inheritance]]. You can also overwrite any of them on a +per-directory and/or per-file basis. -The main means for configuration is the config file: -= Format = += Config file format = -Webber expects a `webber.conf` file in it's root directory. It should look like this: +Webber expects file named "`webber.conf`" file in the root directory. +It could look like this: template: "default" date_format: "%d.%m.%Y" - input_encoding: "iso-8859-1" - output_encoding: "iso-8859-1" plugins: [ - "skeleton", - "hierarchy", - "link", - "read_rst", - "read_html", - "read_copyonly", - "read_markdown", - "template_mako", - ] - exclude_dir: [ - "webber.conf", - "*.tmpl", - ] - exclude_files: [ - ] - -You could also some options with are normally defined by [[commandline]]. -This saves you from specifying them on ever run of webber: + "skeleton", + "hierarchy", + "link", + "read_rst", + "read_html", + "read_copyonly", + "read_markdown", + "template_mako", + "my_plugin", + ] + plugin_dirs: [ + "my_plugins" + ] + +Options for the [[commandline]] can also be specified in the config file: in_dir: "in" out_dir: "out" style_dir: "in/style" verbose: 5 -Beside those entries, you can specify any additional entries that will then -be available in your plugins or templates. += Webber's configuration = + +== in_dir == + +Directory, where the source files (in [[markdown|read_markdown]], +[[rst|read_rst]] or [[html|read_html]] format) reside. + +Default: "`in`". + +See [[commandline]]. + + +== out_dir == + +Directory where webber creates the output files. + +Default: "`out`". + +See [[commandline]]. + + +== style_dir == + +Directory where webber reads the [[template_mako]]. + +Default: "`in/style`". + +See [[commandline]] and "`template`". -= Meaning = == template == -Used by the [[template_mako]] to select the template. +Used by [[template_mako]] to select the template. -== date_format == +Default: `"template`" -Used in `format_date()`. == input_encoding == -Encoding ('utf-8', 'iso-8859-1' etc) used for reading files. +Encoding (e.g. 'utf-8', 'iso-8859-1' etc) used when reading [[source pages|pageformat]]. + +Default: `"iso-8859-1`" + == output_encoding == -Encoding ('utf-8', 'iso-8859-1' etc) used when writing the final HTML pages. +Encoding (e.g. 'utf-8', 'iso-8859-1' etc) used when writing the final HTML pages. + +Default: `"iso-8859-1`" + == plugins == -List of [[plugins]] to load. +List of [[Plugins]] to load. + + +== plugin_dirs == + +List of directories that should be search for [[Plugins]]. Can be empty or +completely omitted. + == exclude_dirs == -List of directories below `cfg.in_dir` to skip. +List of directories below "`in_dir`" to skip. + +Default: "`[]`" + == exclude_files == -List of files below `cfg.in_dir` to skip. +List of files below "`in_dir`" to skip. + +Default: "`['webber.conf', 'directory.conf', '*.tmpl']`" + + +== date_format == + +Used in `format_date()`. The format is the same as in `"man 2 strftime`". + + +== verbose == + +How verbose webber should be. + +See [[commandline]]. + + +== keep_going == -== in_dir, out_dir, style_dir == +If webber should continue after an error. See [[commandline]]. + + += Plugin's configuration = + +Many [[Plugins]] can use custom options. Read more about them in their +documentation. + + += User defined configuration = + +Beside those entries, you can specify any additional entries that will +then be available in user-defined [[Plugins]], [[functions]], +[[macros]] or [[template_mako]]. For example, after adding: + + category: "Webber" + +you can access in [[template_mako]] with: + +

Category: ${page.category}

diff --git a/in/directory.conf b/in/directory.conf new file mode 100644 index 0000000..8ebf1d2 --- /dev/null +++ b/in/directory.conf @@ -0,0 +1 @@ +category: "Webber" diff --git a/in/functions.md b/in/functions.md index 05e0d8d..5b28338 100644 --- a/in/functions.md +++ b/in/functions.md @@ -1,27 +1,41 @@ title: Functions parent: Webber +lang: en ctime: 2009-06-24 +mtime: 2011-01-13 +change: remove reference to show_orphan -= Calling functions = +You can call functions only from [[template_mako]], not from +[[pages|pageformat]]. If you need the latter, look at [[macros]]. -You can call functions only from [[template_mako]]. An example: += Example = Modified ${format_date(mtime)} += List of functions = + Here's list of functions defined by webber and it's default plugins: -== format_date(timestamp) == +== format_date(timestamp, format) == Takes a timestamp (seconds since 1st January 1970) and converts it into -a string, using to `cfg.date_format`. +a string. + +"`format`" is optional. If not used, "`cfg.date_format`" will be used. +Otherwise it should be a format-string as documented by "`man strftime`". For +example, "`%Y-%m-%d`" stands for year-month-date. Defined in `webber.py`. -== get_time() == +== get_time(format) == + +Returns the current date/time as a string. -Returns the current date/time as a string according to `cfg.date_format`. +"`format`" is optional. If not used, "`cfg.date_format`" will be used. +Otherwise it should be a format-string as documented by "`man strftime`". For +example, "`%Y-%m-%d`" stands for year-month-date. Defined in `webber.py`. @@ -63,7 +77,7 @@ You'll need to specify "`root`" if your top-most page isn't named "`Home`". Defined in [[hierarchy.py|hierarchy]], where you find an example. -== get_sitemap(root, show_orphans) == +== get_linear_sitemap(root, level) == Returns all pages as "`(level, page, link)`" tuples, where "`page`" is a "`class File`"-object and link is a relative link from the current page to @@ -71,15 +85,15 @@ Returns all pages as "`(level, page, link)`" tuples, where "`page`" is a You'll need to specify "`root`" if your top-most page isn't named "`Home`". -To put pages into the sitemap that are outside the parent/child relationships, -specify "`True`" for "`show_orphans`". +The "`level`" will by default start at 1. Defined in [[hierarchy.py|hierarchy]], where you find an example. +== get_toc() == -== func == +Returns an unsorted list with the hierarchy of the table-of-contents. -A sample function in the [[skeleton.py|skeleton]]. See below. +Defined in [[toc.py|toc]], where you find an example. = Writing functions = diff --git a/in/hooks.md b/in/hooks.md index fd888dd..4e01224 100644 --- a/in/hooks.md +++ b/in/hooks.md @@ -1,8 +1,34 @@ title: Hooks parent: Webber +lang: en ctime: 2009-06-24 +mtime: 2010-07-06 +change: new introductory text about hooks -= At Startup = +Webber can read and use any number of [[Plugins]], even user-supplied. +Therefore, while writing "`webber.py`", it was not clear which plugins +will exist. So a flexible way to share data between "`webber.py`" and +the plugins was needed. + +Borrowed from IkiWiki came the idea of "Hooks". At various points +during the execution "`webber.py`" fires some hooks. Any plugin can act +to any hook and has a chance to get the current page or configuration +attributes. + +It can then generate local data, change page attributes, generate HTML +or whatever else is needed. + + += How to implement hooks = + +When you program your own [[Plugins]], you simply write python +functions and mark then with the "`@set_hook(name)`" Decorator. See +the Example at addoptions below. + + += Hooks fired at startup = + +When you start "`webber`", the following hooks are executed: == addoptions == @@ -51,21 +77,24 @@ Example: print "in start hook" -= While reading source files = += Hooks fired while reading source files = + +For each file read, the following hooks are fired: == read == Now webber walks the directory tree specified in "`cfg.in_dir"`, excluding -anything from "`cfg.exclude_dir`" and "`cfg.exclude_file"`. For each of the +anything from "`cfg.exclude_dirs`" and "`cfg.exclude_files"`. For each of the remaining files this hook is called. Usually the the "`read_*`" plugins implement this hook. And usually they look -at the file-extension and decide if they the can procecess this file or not. +at the file-extension and decide if they the can proprocecess this file or not. If they do, the plugin should also set "`file.render`" is normally "`html"`. However, it can be something else. In this case "`file.render`" specifies a -hook that get's called for this file. +hook that gets called for this file. -The first hook that returns contents wins, no other hooks will be called. +The first hook that returns contents wins, no further hook-functions +will be called. * "`params.direc`" contains a "`class Directory`" object * "`params.file`" contains a "`class File`" object @@ -100,14 +129,15 @@ Example: params.content = params.content.replace("e", "EEEEE") -= After reading files = += Hooks fired after files are read = + +Now all pages and their meta-information has been read. -At this stage all pages and their meta-information has been read. Now we can -generate additional data, e.g. page hierarchy, tag-clouds, lists of recently -changed files, etc. This is done via the following two hooks. +The following hooks allow plugins to use this data and generate +additional data, e.g. a page hierarchy, tag-clouds, lists of recently +changed files, etc. -The webber-supplied plugin [[hierarchy]] uses this -mechanism. +For example, the plugin [[hierarchy]] uses this mechanism. == scan == @@ -124,20 +154,25 @@ uses this to sort links. * "`params`" is empty. -= While rendering files = -The following hooks are called for each file that has a rendered in -"`file.render`" set. See the "`read"`-hook in how to set it. += Hooks fired while creating HTML = + +The following hooks are called for each file that renders itself. This is indicated +by the "`file.render`" attribute. See the "`read"`-hook on how to set that. If "`file.render`" is "`html"`, then the hooks "`htmlize"`, "`linkify`" and -"`pagetemplate`" are run in this order. Otherwise the hook specified -in "`file.render`" is called. +"`pagetemplate`" are run (in that order). + +Otherwise the hook specified in "`file.render`" is called. This can +even be a custom hook. == htmlize == This hook converts contents into HTML. -The first hook that returns HTML, no other hooks will be called. +If more than one plugin receive this hook, then the first function +returning HTML "wins". No other hook-functions will be called +afterwards. * "`params.direc`" contains a "`class Directory`" object * "`params.file`" has a "`class File`" object @@ -145,8 +180,13 @@ The first hook that returns HTML, no other hooks will be called. == linkify == -This hook should contain any link to html. Implemented by the plugin -[[link]]. +Functions that are called by this hook receive a pre-rendered HTML page. +They can now modify this HTML further, e.g. py converting links to HTML. + +They can directly modify params.file.contents and don't need to return +anything. + +Implemented by the plugin [[link]] and [[toc]]. * "`params.direc`" contains a "`class Directory`" object * "`params.file`" has a "`class File`" object @@ -155,10 +195,10 @@ This hook should contain any link to html. Implemented by the plugin == pagetemplate == The implementation for this is responsible to generate the final html page, -ready to be written. Implemented by [[template_mako]] plugin. +ready to be written. Implemented in the [[template_mako]] plugin. -The first hook that returns a finished HTML page, no other hooks will be -called. +The first hook that returns a finished HTML page wins, no further +hook-functions will be called. * "`params.direc`" contains a "`class Directory`" object * "`params.file`" has a "`class File`" object @@ -166,24 +206,29 @@ called. == copyfile == -This is one local hook, run instead of the "`htmlize"`, "`linkify`" and -"`pagetemplate`" hooks. It's defined and implemented by the plugin -[[read_copyonly]]. +This is an example of a plugin-defined hook. It's run instead of the +"`htmlize"`, "`linkify`" and "`pagetemplate`" hooks by virtue of the +"`file.render`" attribute. -The first hook that returs anything wins, no other hooks will be called. +It's defined and implemented by the plugin [[read_copyonly]]. + +The first hook that returns anything wins, no further hook-functions +will be called. * "`params.direc`" contains a "`class Directory`" object * "`params.file`" has a "`class File`" object = At the end = -Now everythings has been converted to HTML and written out. And we're just -one hook away from finishing webber: +Now everything has been converted to HTML and written out. And we're just +one hook away from finishing program execution: == finish == -This hook is called at the end of webber's execution. No webber-supplied -plugin uses it currently, but you could use this to save local state into some -file. +This hook is called at the end of webber's execution. * "`params`" is empty + +Plugins that use this are [[link]] (to warn about wrong links), +[[google_sitemap]] (to generate the "`sitemap.xml`" file) and [[rss_feed]] +(to generate the "`feed.rss`" file). diff --git a/in/index.md b/in/index.md index 6bc179a..7452287 100644 --- a/in/index.md +++ b/in/index.md @@ -1,12 +1,128 @@ title: Webber +lang: en ctime: 2009-06-24 +mtime: 2010-07-06 +change: added Tutorial + + + + +
Repository:http://gitorious.org/webber
Mailing list:http://groups.google.com/group/webber-generator
+ +*Webber* is a static web-site generation tool, loosely based on ideas +from IkiWiki and my own likings. + +It works by ... + + * reading one [[configuration file|configuration]] + * reading one or more [[page files|pageformat]] + * considering any number of [[plugins|Plugins]] + * execution of [[macros|macros]] + * execution of [[hooks|hooks]] + * rendering through a [[template|template_mako]], using [[functions|functions]] + +Finally webber creates static HTML files that you can upload to your +web-site. I recommend [[sitecopy|http://www.manyfish.co.uk/sitecopy/]] +for this. + += Tutorial = + +First, make an empty directory and change into it: + + $ mkdir web + $ cd web + +Then, get webber: + + $ git clone --depth 1 git://gitorious.org/webber/webber.git + +Now we need a directory for our input files and output files: + + $ mkdir in out + +and create our first page using your favorite ${EDITOR}. It should +look like this: + + $ ${EDITOR} in/index.md + $ cat in/index.md + title: Nothin' about me + + Hi, I'm Holger and I won't tell you more about me :-) + +I'm using [[markdown|read_markdown]] here (you can also use +[[RST|read_rst]] or [[HTML|read_html]], or even have some pages in one +format and other pages in another format). + +Now, webber needs a simple [[config file|configuration]]. Create one, +it should be similar to this: + + $ ${EDITOR} webber.conf + $ cat webber.conf + template: "default" + plugins: [ + "link", + "read_markdown", + "template_mako", + ] + +As you see, we specified a [[template|template_mako]]. That's a HTML +skeleton that webber fills out. Let's create a very simple one: + + $ mkdir in/style + $ ${EDITOR} in/default.tmpl + $ cat in/default.tmpl + + + ${file.title | entity} + + + +

${file.title | entity}

+ ${body} + + + +And finally, we can run webber without any [[command line options|commandline]]: + + $ webber/webber + info: Reading files ... + info: Scanning files ... + info: Rendering files ... + +If "`webber/webber`" is too cumbersome to type, just do this: + + $ ${EDITOR} Makefile + $ cat Makefile + all: + webber/webber + +Now can can simply type "`make`". + +Now you wonder what file has been produced? Let's see: + + $ cat out/index.html + + + Nothin' about me + + + +

Nothin' about me

+

Hi, I'm Holger and I won't tell you more about me :-)

+ + + +You make things way more complex, but that's basically it. + + += More Info = -* [[overview]] * [[pageformat]] * [[configuration]] * [[commandline]] * [[inheritance]] -* [[plugins]] +* [[inheritance]] +* [[Plugins]] * [[read_rst]] * [[read_markdown]] * [[read_html]] @@ -15,7 +131,9 @@ ctime: 2009-06-24 * [[hierarchy]] * [[template_mako]] * [[skeleton]] + * [[google_sitemap]] + * [[rss_feed]] + * [[skeleton]] * [[hooks]] * [[functions]] * [[macros]] -* [[templates]] diff --git a/in/inheritance.md b/in/inheritance.md index 6167c5f..c889a59 100644 --- a/in/inheritance.md +++ b/in/inheritance.md @@ -1,32 +1,58 @@ title: Configuration inheritance linktitle: Inheritance -parent: Webber +parent: Configuration +lang: en ctime: 2009-06-24 +mtime: 2010-07-06 +change: various clarifications, a better example = Overview = -Internally, webber uses a bunch of `Holder` classes to store information -(command-line options, config file options, parameters for a directory, -parameters for a file). +Internally, webber uses a bunch of `Holder` classes to store information. -Each `Holder` "inherits" configuration entries from the layer above: +We have objects of class `Holder` for this entities: -* `options` for command-line options -* `cfg` for entries from the command line -* `direc` for information about a directory -* `file` (either directly or via `get_current_file()` for data about the - currently rendered file +* "`cfg`" stores [[configuration]] and [[commandline]]. +* "`direc`" stores per-directory variables +* "`file`" stores attributes for each file that webber processes -= Example = +This is like the inheritance works: + +* "`direc`" inherits everything from "`cfg`". It can, however, + override anything. In a future version of webber, the "`direc`" + object for directory "`foo/bar/`" will inherit from the + directory object for "`bar/`" and only the last one will inherit from + "`cfg`". But that's not yet coded. +* "`file`" inherits from "`direc`" and again is free to override + anything on a per-file basis. -Due to parsing the [[command line|commandline]] there will exist an entry -`options.style_dir`. -However, you can also access this same value via `cfg.style_dir`, -`direc.style_dir` and `file.style_dir`. Any one of them however could -over-write the settings that originally was in `options`. += Example = -Quite often you'll use this for the page template. In `webber.conf`, you -specify `template: "default"`, which will be used for most pages. Any -page that needs a different template will get `template: history` entry -in it's header. +Due to parsing the [[commandline]] the attribute "`style_dir`" have +some value. If you don't specify one, it will be "default" by default. + +Now the [[configuration]] file "`webber.conf`" gets processed. It may +set "`style`" to "twoframe", if you want a two-frame template for your +web-site. + +Assuming you have a subdirectory with source-code examples. In this +directory you have a file "`directory.conf`" which re-sets it to "default". +This makes the default template work now only for your source-code +examples. + +There's one page where you use the [[hierarchy]] plugin to generate a +sitemap. This one page should have it's own template. Simply make the +[[page|pageformat]] be like this: + + title: Sitemap + template: sitemap + + <% + site = get_linear_sitemap() + %> + diff --git a/in/macros.md b/in/macros.md index 211de19..757e7ad 100644 --- a/in/macros.md +++ b/in/macros.md @@ -1,14 +1,15 @@ title: Macros parent: Webber +lang: en ctime: 2009-06-24 - -= Calling macros = +mtime: 2009-06-26 Macros are executed whenever the sequence -"[[!name]]" or -"[[!name args]]" is in the source-file. +"[[!name]]" or "[[!name +arg1="1" arg2="2"...]]" is found in a [[source page|pageformat]]. -Webber itself doesn't define any macros. +Webber itself doesn't define any macros, that's your task. Use custom +[[Plugins]] for this. = Defining macros = @@ -24,13 +25,17 @@ to be decorated with "`@set_macro(name)`". There's an example in print "in macro skeleton.sample_macro, params:", params return "{ output of sample macro }" -If you call this macro, you'll see the output "[[!sample]]". +If you call this macro, the returned text "`{ +output of sample macro }`" will end up in your HTML file. + +Inside the macro, you can access this parameters: * "`params.name`" contains the name of the macro * "`params.file`" contains the current "`class File`" object -You can submit additional string arguments, e.g. "[[!sample -arg1="string"]]". This will yield +You can submit additional string arguments, e.g. with +"[[!sample arg1="string"]]". Now you get +additionally: * "`params.arg1`" contains "`string`" diff --git a/in/overview.md b/in/overview.md deleted file mode 100644 index 992ba39..0000000 --- a/in/overview.md +++ /dev/null @@ -1,8 +0,0 @@ -title: Overview -parent: Webber -ctime: 2009-06-24 - -*Webber* is a static web-site generation tool, loosely based on ideas -from IkiWiki and my own likings. - -TODO diff --git a/in/pageformat.md b/in/pageformat.md index 67ada75..ad07d35 100644 --- a/in/pageformat.md +++ b/in/pageformat.md @@ -1,47 +1,23 @@ title: Page format parent: Webber +lang: en ctime: 2009-06-26 +mtime: 2010-07-06 +change: enhanced section on page body -Every page contains a header, then a blank line, and then the text that -should show up in the web page. +Every page contains a header, then a blank +line, then the page body. This is the +main text that end up in the rendered HTML page. The header consists of several keywords, followed by a color and a space, -and the the value. +and the the value. After this, the page body comes. -Here's an example: - - title: Impressum - - Hi, I'm Mario and I won't tell you more about me :-) - - -= Your own keywords = - -Inside the template, functions and macros you can access all entries -by "`file.XXXX`" and you're free to invent your own keywords: - - title: Impressum - subtitle: What you should know about this web-site - - Hi, I'm Mario and I won't tell you more about me :-) - -Now you can access "`${file.subtitle}`" in your template and as -"`params.file.subtitle`" in your own [[macros|macros]] or -[[functions|functions]]. - - -= Overriding configuration = - -As "`file`" inherits all configuration from "`cfg`" (see [[inheritance]]), -you can also specify a different template on a per-file basis: - title: Impressum - template: boring_bg - - Hi, I'm Mario and I won't tell you more about me :-) += Page header = +In the page header, you can define any attribute. Some of those keywords +have special meaning for webber or it's plugins: -= Webber's keywords = == title == @@ -51,8 +27,17 @@ Full (long) title for the page. End's up in Very mandatory. Extremely important. You cannot have a page without a title. Never. Forget. The. Title. -Depending on your template it will also be set inside "`

...

`" at the -start of your web page. +Here's a [[template_mako]] excerpt that uses this: + + + + ${file.title | entity} + ... + + +

${file.title

+ ... + == linktitle == @@ -67,6 +52,12 @@ breadcrumbs and a side-menu. Used by [[hierarchy]] to indicate relationship. +== links == + +Used by [[hierarchy]] to indicate relationship. Usually it's better to use +"`parent`" instead. + + == order == All pages with the same "`parent`" will end up below the parent on the @@ -77,11 +68,6 @@ If you don't want this default sort order, you can specify your own ordering. The default order is 100, so anything with a lower order will show up on the top, anything higher at the bottom of the side-menu. -== links == - -Used by [[hierarchy]] to indicate relationship. Usually it's better to use -"`parent`" instead. - == ctime == @@ -94,6 +80,28 @@ the document creation date/time. Examples: If you don't specify this, then the documents "`mtime`" will be used instead. +Here's a [[template_mako]] excerpt that uses this: + + <%def name="footer()">\ + <% + mtime = format_date(file.mtime) + ctime = format_date(file.ctime) + %> + Created\ + % if ctime == mtime: + ${mtime} \ + % else: + ${ctime}, modified ${mtime} \ + % endif + + \ + +This uses the named block feature of Mako, you can then place this +text into your template with something like this: + +
${self.footer()}
+ + == mtime == Here you can specify an ISO formatted date and or time specifier, which contains @@ -105,39 +113,65 @@ the document modification date/time. Examples: If you don't specify this, then the "last-modified"-time from the file-system will be used instead. +For an example, look at ctime above. + == template == Allows you to override the default template. Just specify the pure file -name. For convenience, you can ommit "`.tmpl`". +name. For convenience, you can omit "`.tmpl`". title: Blog template: history +== hide == + + hide: true + +will hide the generated page from in the plugins [[hierarchy]] and [[toc]]. + + == description == Anything you specify here will be accessible in the template as ${description}. -You can use this for HTML meta information, see [[template_make]]. +You can use this for HTML meta information, see [[template_mako]]. If you don't specify a description, then ${description} will be the empty string. +Here's a [[template_mako]] excerpt that uses this: + + + ... + % if len(description): + + % endif + ... == keywords == Anything you specify here will be accessible in the template as ${keywords}. -You can use this for HTML meta information, see [[template_make]]. +You can use this for HTML meta information, see [[template_mako]]. If you don't specify a description, then ${keywords} will be the empty string. +Here's a [[template_mako]] excerpt that uses this: + + + ... + % if len(keywords): + + % endif + ... + == main_url == Used by [[google_sitemap]]: -Internally, [[Webber]] works with relative URLs and is quite agonistic about -the final website. However, the [[google_sitemap]] plugin needs absolute URLs, -complete with host name. So we need this configuration ... +Internally, [[Webber]] works with relative URLs and is quite agnostic +about URL of the final website. However, the [[google_sitemap]] plugin +needs absolute URLs, complete with host name. Used by [[google_sitemap]]: @@ -161,3 +195,64 @@ Should be one of the following values: * monthly * yearly * never + + += Your own keywords = + +Inside the template, functions and macros you can access all entries +by "`file.XXXX`" and you're free to invent your own keywords: + + title: Impressum + subtitle: What you should know about this web-site + + Hi, I'm Mario and I won't tell you more about me :-) + +Now you can access "`${file.subtitle}`" in your template or +"`params.file.subtitle`" in your [[macros|macros]] and +[[functions|functions]]. + + += Page body = + +== Markdown page body == + +Used for files ending with "`*.md`" and implemented by [[read_markdown]]. + +Here's an example: + + title: Nothin' about me + + Hi, I'm Holger and I won't tell you more about me :-) + + +== RST formatted == + +Used for files ending with "`*.rst`" and implemented by +[[read_rst]]. + + + +== HTML formatted == + +Used for files ending with "`*.html`" and implemented by [[read_html]]. + +This is actually not really HTML, only the page body is HTML. +You can use it when RST or Markdown can't format the contents the way +you like it, e.g. when using complex tables. + +Here's an example: + + title: Beruflicher Werdegang + linktitle: Werdegang + parent: Beruf + keywords: Lebenslauf, Werdegang + sitemap_changefreq: yearly + ctime: 2004-08-30 + mtime: 2009-12-12 + +
+ 1979 + 1980 + ... +
+ ... diff --git a/in/plugins/directory.conf b/in/plugins/directory.conf new file mode 100644 index 0000000..86c7fbe --- /dev/null +++ b/in/plugins/directory.conf @@ -0,0 +1 @@ +category: "Webber plugins" diff --git a/in/plugins/google_sitemap.md b/in/plugins/google_sitemap.md index 6d49b86..f30662c 100644 --- a/in/plugins/google_sitemap.md +++ b/in/plugins/google_sitemap.md @@ -2,9 +2,11 @@ title: Google Sitemap generation linktitle: google_sitemap.py parent: Plugins keywords: Google, XML, Sitemap generator +lang: en ctime: 2009-06-26 +mtime: 2009-06-26 -This plugins write an XML "`sitemap.xml`" file into the out-directory. The +This plugin writes an XML file "`sitemap.xml`" into the out-directory. The format is documented at [[http://www.sitemaps.org]]. @@ -47,7 +49,7 @@ e.g.: Disallow: /logs/ Sitemap: http://www.holgerschurig.de/sitemap.xml -Also make sure that your "`robots.txt`" file get's copied, by adding +Also make sure that your "`robots.txt`" file gets copied, by adding copy_files: [ ... diff --git a/in/plugins/hierarchy.md b/in/plugins/hierarchy.md index 15388b1..f2b42ec 100644 --- a/in/plugins/hierarchy.md +++ b/in/plugins/hierarchy.md @@ -1,7 +1,9 @@ title: Generate hierarchy linktitle: hierarchy.py parent: Plugins +lang: en ctime: 2009-06-26 +mtime: 2009-06-26 This is one of the more complex plugins, used to generate menus and breadcrumbs. For this, it reads certain keyword from the @@ -93,11 +95,11 @@ Here's a sample Mako template excerpt: = Generation of a side-menu = This again is done via a suitable [[template_mako]]. The -template uses the function "`get_sidemenu()`" and returns (level, +template uses the function "`get_sidemenu()`" which returns (level, part_of_path, is_current, title, link) tuples. Again all links are relative to the calling page. -* "`level`" is the indendation level, starting with 0. You can use this for +* "`level`" is the indentation level, starting with 0. You can use this for CSS "`id=`" or "`class`" attributes * "`part_of_path`" is a flag telling you if the mentioned page is part of your path, i.e. if the specified page is in the breadcrumbs. @@ -105,7 +107,8 @@ to the calling page. * "`title`" is the full title for the page * "`link`" is the relative URL to the page -Here's a sample Mako template excerpt that converts this into a HTML menu: +Here's a sample [[Mako template|template_mako]] excerpt that converts +this into a HTML menu: