Introduction

============

Pelican is a static site generator, written in Python.

This repository contains a pre-fabricated Pelican project and theme

you can use as a foundation on which to build your own static HTML

websites.

Pelican, together with Git and rsync, make it easy to compose, archive

and deploy static HTML websites.

Installing Pelican

==================

The easiest way to install Pelican is within a python virtual

environment.  You can create a virtual environment à la carte with

virtualenv, or manage several virtual environments under a single

directory with virtualenvwrapper::

    virtualenv cwi-pelican

    cd cwi-pelican

    . ./bin/activate

Once the virtual environment has been created and activated, use pip

to install Pelican and its dependencies::

    pip install pelican

If you plan on using Markdown as a markup format, you’ll need to install the Markdown library::

    pip install Markdown

Typographical enhancements can be enabled in your settings file, but

first the requisite Typogrify library must be installed::

    pip install typogrify

Installing Pelican project template

-----------------------------------

To kick start your website development we have created a

pre-fabricated Pelican theme and project template with example

content. While you can install the template anywhere you like, for

this example, please clone the cwi-pelican-template in the root of

your Pelican virtual environment. Don't forget to use your own

username in the url::

    git clone https://<username>@scm.cwi.nl/ITF/cwi-pelican-template cwi

Installing the Pelican CWI theme

--------------------------------

The cwi project template uses a corresponding CWI theme, but it must

be installed before Pelican can use it::

    pelican-themes --symlink ${PWD}/cwi/theme/cwi

Usage

=====

To generate html output, go to the project directory and invoke Pelican via make::

    cd cwi/projects/cwi

    make html

Previewing

----------

Pelican has its own built-in server. You can invoke it with make; or

you can regenerate the HTML and serve it in one command::

    make html serve

The server uses port 8000 by default. After starting the server point

you browser to the url: localhost:8000.

Uploading the generated HTML to a server

----------------------------------------

The Pelican Makefile contains several targets for uploading its

generated HTML. List all make's targets with::

    make -n

To use rsync, edit the Makefile and customize the values of SSH_HOST,

SSH_USER and SSH_Target_DIR.

If CWI is hosting your site, SSH_HOST and SSH_TARGET_DIR name the host

and document root configured for you by ITF staff.

Archiving your site

-------------------

The url from which you cloned the cwi-pelican-template repository is

called the clone's 'origin.' To archive your clone you should change

its origin to point to a new repository and push it there. For

example, if I had created a new repository at scm.cwi.nl named

itf-pelican-site, I could push my site there with the following two

commands::

    git remote add origin https://guravage@scm.cwi.nl/ITF/itf-pelican-site

    git push -u origin master

Creating new Pelican projects

-----------------------------

Pelican provides a scrip, appropriately named 'pelican-quickstart', to

help create new project hierarchies.  To use it, go to the projects

directory and invoke 'pelican-quickstart' at the command prompt. The

script will solicit your answers to a number of questions, and

generate your new project hierarchy accordingly.

The CWI Template and Theme

==========================

The project content is a hierarchy of folders and files containing

your content, the CWI theme and the Pelican generated HTML.

Content hierarchy structure

---------------------------

The first and most important hierarchy is the one that holds the

content of your website. Here is where you add your content that

becomes pages on your static website.  Browse through the content

hierarchy to familiarize yourself with its structure and contents.

Folder names become Pelican categories, so folders named, 'blog',

'news', 'pages', 'private' and 'static' contain exactly what you

expect them to have. By default, files in the blog folder are

displayed on the index page. Files in the pages folder produce

corresponding tabs. The events.md file contains explicit links to

files in the news folder. The about.md file contains a link to a

static PDF file.

You can customize how Pelican will handle your content by editing the

configuration files: pelicanconf.py and publishconf.py::

    ├──  projects

    │   ├──  cwi

    │   │   ├──  pelicanconf.py

    │   │   ├──  publishconf.py

    │   │   ├──  develop_server.sh

    │   │   ├──  fabfile.py

    │   │   ├──  Makefile

    │   │   ├──  content

    │   │   │   ├──  blog

    │   │   │   │   └──  cwi.md

    │   │   │   ├──  extras

    │   │   │   │   ├──  .htaccess

    │   │   │   │   ├──  .htpassword

    │   │   │   ├──  images

    │   │   │   ├──  news

    │   │   │   │   ├──  energy_projects.md

    │   │   │   │   ├──  jos_baeten_uva.md

    │   │   │   │   └──  linda_hardman_acm.md

    │   │   │   ├──  pages

    │   │   │   │   ├──  about.md

    │   │   │   │   ├──  contact.md

    │   │   │   │   ├──  events.md

    │   │   │   │   └──  news.md

    │   │   │   ├──  private

    │   │   │   │   └──  private.md

    │   │   │   └──  static

    │   │   │       └──  annual-report.pdf

CWI Theme hierarchy

-------------------

        │   │           ├──  vimeo.png

        │   │           └──  youtube.png

        │   └──  templates

        │       ├──  analytics.html

        │       ├──  archives.html

        │       ├──  article.html

        │       ├──  article_infos.html

        │       ├──  author.html

        │       ├──  authors.html

        │       ├──  base.html

        │       ├──  base.html~

        │       ├──  category.html

        │       ├──  comments.html

        │       ├──  disqus_script.html

        │       ├──  github.html

        │       ├──  index.html

        │       ├──  page.html

        │       ├──  period_archives.html

        │       ├──  piwik.html

        │       ├──  tag.html

        │       ├──  taglist.html

        │       ├──  tags.html

        │       ├──  translations.html

        │       └──  twitter.html

Output hierarchy structure

--------------------------

Here is the structure of the HTML Pelican generates::

    ├──  projects

    │   ├──  cwi

    │   │   ├──  output

    │   │   │   ├──  about.html

    │   │   │   ├──  archives.html

    │   │   │   ├──  author

    │   │   │   │   └──  moe-howard.html

    │   │   │   ├──  authors.html

    │   │   │   ├──  categories.html

    │   │   │   ├──  category

    │   │   │   │   └──  blog.html

    │   │   │   ├──  feeds

    │   │   │   │   ├──  all.atom.xml

    │   │   │   │   └──  blog.atom.xml

    │   │   │   ├──  index.html

    │   │   │   ├──  pages

    │   │   │   │   ├──  .htaccess

    │   │   │   │   ├──  .htpassword

    │   │   │   │   ├──  about.html

    │   │   │   │   ├──  contact.html

    │   │   │   │   ├──  energy_project.html

    │   │   │   │   ├──  events.html

    │   │   │   │   ├──  jos_baeten.html

    │   │   │   │   ├──  lynda_Hardman.html

    │   │   │   │   ├──  news.html

    │   │   │   │   └──  private.html

    │   │   │   ├──  static

    │   │   │   │   └──  annual-report.pdf

    │   │   │   ├──  tags.html

    │   │   │   └──  theme

    │   │   │       ├──  css

    │   │   │       │   ├──  main.css

    │   │   │       │   ├──  main.css~

    │   │   │       │   ├──  pygment.css

    │   │   │       │   ├──  reset.css

    │   │   │       │   ├──  typogrify.css

    │   │   │       │   └──  wide.css

    │   │   │       └──  images

    │   │   │           └──  icons

    │   │   │               ├──  aboutme.png

    │   │   │               ├──  bitbucket.png

    │   │   │               ├──  cwi.jpg

    │   │   │               ├──  cwi_orig.jpg

    │   │   │               ├──  delicious.png

    │   │   │               ├──  facebook.png

    │   │   │               ├──  github.png

    │   │   │               ├──  gitorious.png

    │   │   │               ├──  gittip.png

    │   │   │               ├──  google-groups.png

    │   │   │               ├──  google-plus.png

    │   │   │               ├──  hackernews.png

    │   │   │               ├──  lastfm.png

    │   │   │               ├──  linkedin.png

    │   │   │               ├──  reddit.png

    │   │   │               ├──  rss.png

    │   │   │               ├──  slideshare.png

    │   │   │               ├──  speakerdeck.png

    │   │   │               ├──  stackoverflow.png

    │   │   │               ├──  twitter.png

    │   │   │               ├──  vimeo.png

    │   │   │               └──  youtube.png

Pelican Documentation

=====================

You will find answers to all your Pelican questions in the Pelican