Oben Sonne avatar Oben Sonne committed f37a723

Add documentation for hooks and virtual pages

Comments (0)

Files changed (1)

 [clevercss]: http://sandbox.pocoo.org/clevercss/
 [less]: http://lesscss.org/
 
+### Pre- and post-convert hooks
+
+All pages converted by Poole may be processed by custom code in `macros.py`
+using *hook* functions. In particular, any function whose name starts with
+`hook_preconvert_` is run after source markdown files have been parsed but
+not yet converted. Similarly, any function whose name starts with
+`hook_postconvert_` is run after the content of pages has been converted to
+HTML (but still without the skeleton HTML given in the project's `page.html`
+file).
+
+Pre-convert hooks are useful to preprocess the markdown source and/or to
+generate new virtual pages based on existing real pages:
+
+    def hook_preconvert_foo():
+        # important: replace all foos by bars in every page
+        for p in pages:
+            p.source = p.source.replace("foo", "bar")
+        # create a new virtual page which still has a foo
+        p = Page("foo.md", virtual="The only page with a *foo*.", title="Foony")
+        pages.append(p)
+
+Virtual pages can be created by providing a virtaul source filename relative
+to the project's input folder and corresponding markdown content. Page
+attributes (e.g. `title`) may be given as additional keyword arguments but
+may also be encoded in the markdown source as in real markdown input files.
+
+A common use case for post-convert hooks is to generate full content RSS feeds:
+
+    def hook_postconvert_rss():
+        # this is kind of pseudo code
+        rss = ...
+        for p in pages:
+            rss.add_item(..., r.html)
+        rss.save(".../rss.xml")
+
+More practical and detailed usage examples of hooks and virtual pages can be
+found in the recipes.
+
 ### Recipes
 
 You can do some pretty fancy and useful things with inlined Python code and
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.