This article explains myblog layout.
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.
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,
+- 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
Following is the general idea on how pagd.myblog layout works,
+------+ +---------+ +-------------+
|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.
_context.json files providing context information for all pages under the sub-directory or <pagename.json> 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.
- 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).
- site
- Site instance. Every page under the site will refer to the same site instance.
- page
- Page instance.
- title
- Page title - will be highlighted as document title, and also added under html <title> 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.
- 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 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.