Myblog layout plugin
===================
This article explains myblog layout.
directory structure
-------------------
One of the first thing a user must do is to create a site-layout using one of
the layout plugin - in this case `pagd.myblog`.
.. code-block:: bash
pagd -s /home/me/blogsite -l pagd.myblog create
``-s`` switch specifies the directory path, also called as sitepath, where
the layout is created. If left unspecified sitepath defaults to
current-working-directory.
``-l`` switch specifies the layout plugin to be used for creating the site
layout. If left unspecified uses a default layout.
Refer to the glossary_ page before continuing further. The above command will
create following directory tree,
.. code-block:: text
+- config.json
+- _contents/
| +- _context.json
|
+- media/
| +- myblog.css
| +- pygments.css
|
+- _templates/
+- _default.ttl
+- _footer.ttl
+- _header.ttl
+- _head.ttl
+- index.ttl
+- _social.ttl
+- _social/
+- disqus.html
- ``config.json`` contains a dictionary of settings that will direct pagd
command like script. Individual settings parameter are explained further
down.
- ``_context.json`` context information that are applicable to all pages and
pages under all sub-directories.
- ``myblog.css`` style customization can be done through this file.
- ``_default.ttl`` template will be used for all other pages, if a matching
template is not found for a page under _contents/ sub-directory.
- ``_footer.ttl`` constitute the footer portion of site pages. You can add
acknowledgments, copyright notice under this template.
- ``_header.ttl`` constitute the header portion of site pages. You can add your
site-wide navigation links inside this template file.
- ``_head.ttl`` will go under
element of the page. Both index.ttl and
_default.ttl templates include them.
- ``index.ttl`` directly maps to ``_contents/index.`` file. This
template is used only for the index-page.
- ``_social.ttl`` adds social sharing features for your site. Uses
`social_sharing` configuration parameter from `config.json`.
- ``_social/`` add all html snippets that you obtain from disqus, twitter,
facebook etc... under this directory.
Following is the general idea on how `pagd.myblog` layout works,
.. code-block:: text
+------+ +---------+ +-------------+
|layout|--->|generator|<---->|page-iterator|
+------+ +---------+ +-------------+
| ^
| | +------------+
V +<---------|page-context|
+---------+ | +------------+
|Html-page| |
+---------+ | +-------------+
| +<---------|page-template|
| | +-------------+
V +------------+
+--------+ |page-content|
|web-site| +------------+
+--------+
Generator is normally called through `gen` sub-command, the sole purpose is to
generate the static site form a source layout, which is described above.
- generator iterates over every page under the _contents/ sub-directory.
- files under _contents/ sub-directory can further be organised as
sub-directories and the relative path of each file will correspond to
relative-url-path for generate page.
- each page is represented as :class:`Page` object and contains relevant
information like, pagename, relative-path, urlpath, contentfiles and
context.
- context for each page is populated using sub-directory's default-context,
page's corresponding json file, page-metadata.
- page content is translated to html content using an `IContent` plugin.
- template for each page is searched under _template/ sub-directory using
file's relative path. If file specific template is not found, then a default
template from relative-path's parent sub-directory will be used.
- and finally the generated html will be saved under sitepath. Note that
template and content authors must take this into account, especially when
referring to files under media/ path.
external context
----------------
_context.json files providing context information for all pages under the
sub-directory or files providing context attributes
to specific pages can refer to external source of context through `_xcontext`
attributes. Value of this attribute is a comma separated list of plugin names,
in canonical format like `pagd.git`, that refer to IXContext plugins. While
generating the site such references will be fetched and page's context
dictionary will be updated.
Repository integration is accomplished using this feature.
configuration settings
----------------------
layout,
layout type to be used, like e.g, ``pagd.myblog``.
tayra.ttlcompiler.*
configuration parameters prefixed with ``tayra.ttlcompiler.`` will be
passed on to tayra_ template compiler.
age_scale
configuration parameters for repository plugins like ``pagd.git``,
``pagd.hg`` should have one of the following - "year", "month", "week",
"day", "hour", "second". While generating the pages, git plugin will
gather createdon and last_modified dates from repository, and use this
configuration to convert date to age format relative to current date/time.
set this value if you are going to periodically and frequently generate
the pages.
google_webfonts
list of, comma-separated, google's webfonts reference. Refer to
google-webfonts_ on how to add web-fonts from google's site.
style
property map of css style that will be applied on page's body element.
show_email
boolean, if true will added email reference to page's author.
social_sharing
list of, comma-separated, string of social-networks that can be used to
share a page. For eg., ``google+,twitter``, for each social network that are
mentioned you must add a corresponding `twitter.html`, `google+.html`
under ``_templates/_social/`` directory.
disqus
boolean, if true will add commenting system for the page using an external
commenting service like disqus. Make sure to populate
``_templates/disqus.html`` file with a corresponding snippet.
skip_context
list of, comma-separated, context attribute names that should be skipped
for all pages.
copyright,
copyright string that will be displayed in page footer.
configuration settings like ``disqus``, ``show_email``, ``social_sharing``,
``copyright``, ``google_webfonts``, ``style`` are automatically made available
in page-context. At the end of it, even configuration information is part of
context and this gives a unified picture to template developers, while users
still have a notion of configuring the site (using config.json) and
customizing pages (using _context.json).
context information
-------------------
site
:class:`Site` instance. Every page under the site will refer to the same
`site` instance.
page
:class:`Page` instance.
title
Page title - will be highlighted as document title, and also added under
html tag.
summary
Page summary - will come under page's title.
layout
layout type to be used. Same as `layout` parameter from configuration
settings.
author
name of page's author.
email
author's email-id.
last_modified
page's last modified time.
createdon / date
page creation time.
_xcontext,
comma separated string of plugin names (in canonical format) to fetch page
context from external source, like from repository, network or from
persistent data store.
IContent,
plugin name for translating :class:`Page` to html. Plugins supplied with
the package - `pagd.native`, `pagd.pandoc` etc ... if left unspecified
then default plugin will be used. Most probably the default plugin is
`pagd.native`.
filetype,
interpret content-file as `filetype`. Note that if more than one contentfile
is present for the same page, this settings will be ignored. If left
un-specified, file extension will be used to guess its file-type.
articles,
list of tuple, (filepath, html-content), that can be used to populate the
page-template during site-generation.
template
template location in asset-specification format to be used for the
content-page.
templatetype,
interpret the template file as given type. If left unspecified template type
will be guessed based on file extension.
.. _google-webfonts: http://www.google.com/fonts
.. _tayra: http://pythonhosted.org/tayra