Merge pull request #468 from DirkR/textbundle-docs

Extend textbundle plugin documentation

textbundle/Readme.md

@@ -1,12 +1,12 @@
 # Textbundle Reader
 
 This plugin helps you creating posts from Textbundles
-(http://textbundle.org/spec/).
+(<http://textbundle.org/spec/>).
 
-In anutshell a textbundle is a folder with a ".textbundle" name suffix and
-a predefined folder hierarchy. The Markdown text is always in a file "text.md",
+In a nutshell a textbundle is a folder with a `.textbundle` name suffix and
+a predefined folder hierarchy. The Markdown text is always in a file `text.md`,
 all referenced assets (images, videos, etc.) are located in a subfolder named
-"assets/" and a file "info.json" (obviously in JSON format) provides some meta
+`assets/` and a file `info.json` (obviously in JSON format) provides some meta
 data.
 
 ## Dependency
@@ -18,13 +18,82 @@ Install it with:
 pip install Markdown
 ```
 
-## Usage
+## Installation and configuration
 
-Install the textbundle plugin and add it to the PLUGINS setting:
+Install the textbundle plugin and add it to the `PLUGINS` setting in
+`pelicanconf.py`:
 
 ```
 PLUGINS = [
     'textbundle',
-    ...
+     ...
+    ]
+```
+
+Furthermore the content of the `ARTICLE_PATHS` setting has to be appended to the
+`STATIC_PATHS` list.
+
+```
+ARTICLE_PATHS = ['posts']
+...
+STATIC_PATHS = [
+    'posts',
+     ...
     ]
 ```
+
+The output content pages has to be generated into files `index.html` inside the
+folder named after the page slug or article slug. This way the assets can be
+placed next to the content file and do not interfere with asset files of other
+textbundles.
+
+A working example of article/page slugs and output URLs are:
+
+```
+ARTICLE_URL = 'post/{slug}/'
+ARTICLE_SAVE_AS = 'post/{slug}/index.html'
+
+PAGE_URL = '{slug}/'
+PAGE_SAVE_AS = '{slug}/index.html'
+```
+
+## Usage
+
+Inside a Markdown file (the file `text.md` in a textbundle) the files from the
+`assets/` folder are referenced using relative pathnames and the `{attach}`
+suffix, as described in the [pelican documentation][pelican-docs], section
+"Linking to static files".
+
+An article with the slug "my-blog-post" and an image named `screenshot.png` in
+the `assets/` folder contains a link like this:
+
+```
+![alt text]({attach}assets/screenshot.png "title text")
+```
+
+Assuming the above mentioned settings in `pelicanconf.py` the following files
+are generated in the output folder:
+
+* posts/my-blog-post/index.html
+* posts/my-blog-post/assets/screenshot.png
+
+Further examples can be found in my personal blog ([GitHub][niebegegnet-gh],
+[Link][niebegegnet-blog]).
+
+### Generating the boilerplate
+
+To create a new post I have a shell function `new_post` defined in `~/.bashrc` or
+`~/.zshrc`. Running
+
+```
+new_post "My next blogpost"
+```
+
+at the shell prompt creates the file structure of a textbundle in the posts dir
+of my blog project. The code can be found in my [new_post
+gist](https://gist.github.com/DirkR/aabb1b6fa97ff92ed86a).  The path names
+are hardcoded as it's quite easy to adopt the script to one's personal needs.
+
+[pelican-docs]: http://docs.getpelican.com/en/latest/content.html#linking-to-static-files
+[niebegegnet-gh]: https://github.com/DirkR/niebegeg.net
+[niebegegnet-blog]: https://niebegeg.net

textbundle/textbundle.py

@@ -7,7 +7,6 @@ from glob import glob
 
 from pelican import readers
 from pelican import signals
-#from pelican.utils import pelican_open
 from markdown import Markdown
 
 logger = logging.getLogger(__name__)
@@ -41,6 +40,10 @@ def copy_page_assets(generator):
 
 
 def inspect_content_items(content_items, output_path):
+    """
+    Check if there are files in the assets/ foldr of a textbundle have to be
+    copied to the output folder.
+    """
     for item in content_items:
         foldername = os.path.join(
             output_path,
@@ -53,6 +56,9 @@ def inspect_content_items(content_items, output_path):
 
 
 def copy_assets_to_outputfolder(assets, foldername):
+    """
+    Copy all files from the assets/ folder of a textbundle to the output folder.
+    """
     if not os.path.exists(foldername):
         os.makedirs(foldername)
     for asset in assets: