Pagd: Customizing blog using pagd

May 19, 2013

Read this article to know how to set up your blog site with pagd and host it using github. Continue reading if you want to customize your site with pagd.

Adding fonts with google-webfonts

Pagd by default comes with inconsolata font from google-webfonts. Pagd templates will load all font references from config.jsonfile present under the layout’s root directory. Just append the reference URL to the list of google_webfonts. To apply one of the loaded fonts to page’s <body> element - set the font-family attribute in config.json. The style property object in config.json will be converted to a string of semi-colon separated list of CSS properties and applied to page’s body element as its style attribute.

    { "google_webfonts" : [
       "http://fonts.googleapis.com/css?family=Inconsolata"
      ],
      "style" : {
          "font-family" : "Inconsolata"
      }
    }

Note that above settings are global to all pages in the site. If you want to customize the fonts for specific elements in the page, then you must customize them using media/myblog.css.

Let your readers mail you directly

Pagd can generate a mailto: hyper-reference at the bottom of every blog article, if you provide email meta-data for your pages. If you are managing your site with git or mercurial then, you can add your email-id as part of .gitconfig or .hgrc file. Otherwise, you can simply add your email id along with the page content as meta data, like,

:title: <Page title for this blog article>
:author: prataprc
:email: <emailid>

...
rest of the content
...

Note if you are not providing your email id as part of repository meta-data, they you will have add it manually for every blog article that you are creating under _contents sub-directory.

Copyright

Add your copyright information in config.json file placed under your site layout’s root directory, for eg.,

{ "copyright" : "&copy; 2013 Pratap Chakravarthy" }

Advanced customization

Once you are comfortable adding pages under _contents/ directory and managing your config.json, you must go through pagd package documentation and learn now pagd.myblog layout is organized. Subsequently you can alter your site layout either using CSS or directly by changing the template files. This section gives a short introduction on them.

Customizing with CSS

Html elements generated by pagd.myblog template are selectable using CSS id and class names. Under your site-layout, media/myblog.css file contains the necessary styling attributes for your pages. It is generally divided into,

CSS reset declarations.
standard element styling applicable to all pages.
targeted styling for specific html elements.

You can freely modify / add / remove CSS declaration as it suites your site.

Customizing with templates

All template files for pagd.myblog layout can be found under _templates/ sub-directory and uses tayra templating language to describe them. Experimental support is available for mako and jinja2 templates, but use them only if you are well-versed with pagd-tool. Pages generated by pagd.myblog layout plugin is made up of three parts, header, container and footer.

index.ttl directly maps to _contents/index.<format> file. This template is used only for the index-page.
_default.ttl template will be used for all other pages, if a matching template is not found for a page under _contents/ sub-directory.
_head.ttl will go under <head> element of the page. Both index.ttl and _default.ttl templates include them.
_header.ttl constitute the header portion of site pages. You can add your site-wide navigation links inside this template file.
_footer.ttl constitute the footer portion of site pages. You can add acknowledgments, copyright notice under this template.
_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.

To keep a tab on pagd - follow [project at github][pagd-gh-link] and post your queries to their mailing-list.