Commits

Rafael Martins committed c95712f

added attachments example to the repository template and some documentation

Comments (0)

Files changed (4)

blohg/repo_template/content/about.rst

 ========
 
 This is an example page!
+
+Here is an attachment example:
+
+.. attachment-image:: mercurial.png
+
+And here is the link for this attachment: :attachment:`mercurial.png`

blohg/repo_template/content/attachments/mercurial.png

Added
New image
 --------------------
 
 The repository structure is pretty easy to understand::
-
+    
     blohg/repo_template/
     |-- config.yaml
     |-- content
     |   |-- about.rst
+    |   |-- attachments
+    |   |   `-- mercurial.png
     |   `-- post
     |       |-- example-post.rst
     |       `-- lorem-ipsum.rst
         |-- post_list.html
         `-- posts.html
 
+
 - ``config.yaml`` is the main configuration file.
-- ``content/`` is the main directory for content (pages and posts). Posts are stored
-  at ``content/post/``. Pages are stored anywhere inside ``content/``.
-- ``static/`` is the directory with static files used by your blog, like css files
-  or images.
+- ``content/`` is the main directory for content (pages, posts and attachments).
+  Posts are stored at ``content/post/``, pages are stored anywhere inside
+  ``content/`` and attachments are stored at ``content/attachments/``
+- ``static/`` is the directory with static files used by your blog, like css
+  files or images.
 - ``templates/`` is the directory with your Jinja2 templates.
 
 
 This is useful if you want to migrate content from another blog.
 
 
-reStructuredText directives
----------------------------
+Adding attachments
+------------------
+
+You may want to add some images or attach some files to your post/page. To atach
+a file, just put it in the directory ``content/attachments`` of your Mercurial
+repository and use one of the custom reStructuredText_ directives or roles to
+use it in your post/page.
+
+Directive ``attachment-image``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Identical to the ``image`` directive, but loads the image directly from your
+``content/attachments`` directory.
+
+Usage example:
+
+.. code-block:: rest
+    
+    .. attachment-image:: mercurial.png
+
+Directive ``attachment-figure``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Identical to the ``figure`` directive, but loads the image directly from your
+``content/attachments`` directory.
+
+Usage example:
+
+.. code-block:: rest
+    
+    .. attachment-figure:: mercurial.png
+       
+
+Interpreted Text Role ``attachment``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 
+
+Interpreted Text Role that generates a link to the attachment (``reference``
+node).
+
+Usage example:
+
+.. code-block:: rest
+    
+    This is the attachment link :attachment:`mercurial.png`
+
+
+Additional reStructuredText directives
+--------------------------------------
+
+These are some additional custom directives, that adds some interesting
+functionality to the standard reStructuredText_ syntax.
 
 Youtube
 ~~~~~~~