How do I write this blog

This blog site is written in Markdown and converted into a website using Pelican. In this post, I am going to share how the whole process works.

Why Pelican

It is mostly a personal choice. Python is my goto language. So I was looking for Python based static site generators and Pelican was the top contender. Given below is a partial list of things that I liked about Pelican:

  • The content can be authored in Markdown or reStructuredText. You don't need to learn any new syntax.
  • From design point of view, Pelican is written as a blog site generator. Pelican understands dates, tags, categories, etc.
  • Developing a blog template of your own is dead simple. Though I didn't venture to develop a template of my own, I took one and customized it easily. All templats are written Jinja2.
  • You can edit, view and live reload your changes offline before making it live.
  • The directory structure is so simple. Nothing magic going on. content/ subdirectory contains all contents.

Terminology

  • Articles These are the blog posts. Any file you create under the content/ directory is treated as a blog post.
  • Pages These are the pages that are not associated with a time line. For instance, "About" or "Contact Us" pages. Any file you create under content/pages/ directory.
  • Metadata This is the set of key-value pairs that you place at the top of the file. This information is consumed by Pelican. This does not show up as-is in the generated output. For instance, you can let Pelican know that you are still working on a post by specifying the status as "draft" in metadata: Status: draft. This metadata is also known in publishing world as Front matter.

Workflow

  • Create a new file under content. Say content/demo_post.md.
  • Once you have written down your content, just issue the command pelican -r --listen. Pelican will print a message showing in which port it is listening.
$ pelican -r --listen
  --- AutoReload Mode: Monitoring `content`, `theme` and `settings` for changes. ---
Serving site at: http://127.0.0.1:8000 - Tap CTRL-C to stop

-> Modified: settings, content, theme, images. re-generating...
Done: Processed 8 articles, 3 drafts, 0 hidden articles, 0 pages, 0 hidden pages and 0 draft pages in 0.18 seconds.
  • You can view the site by visiting http://127.0.0.1:8000. If you make any changes to your contents, they will be autoreloaded.
  • Once you are satisfied with your content, you can regenerate the entire website by simply invoking pelican: pelican -o .

Thats it. Your new site ready to be published.

Tips

  • I have a starter tempalte with FIXME placeholders that I copy and start replacing all FIXME instances. This is the fastest way to get started with writing a page.
  • As mentioned earlier, I always have two tabs open while writing content. One for vim and one for running Pelican live server.
  • If I am still working on the content, I mark the page with draft status. Draft status pages are not rendered in the live site (i.e. their links will not be visible to the external world). You can visit them by navigating the /drafts path in your web site.

Next steps

Pelican has one of the best written documentation. You can get started in no time by going through their documentation here. These two chapeters very useful: Quickstart and Writing content.

links

social