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 <https://virtualenv.pypa.io/en/latest/>`_ , or manage

several virtual environments under a single directory with

`virtualenvwrapper <http://virtualenvwrapper.readthedocs.org/en/latest/>`_::

    virtualenv cwi-pelican

    cd cwi-pelican

    . ./bin/activate

Once your 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 Git repository in

the root of your Pelican virtual environment.

You can clone the cwi-pelican template in one of two ways. First, you

can fork the repository directly in the Rhodecode server.  Point your

browser to https://scm.cwi.nl/ITF/cwi-pelican-template, choose 'Fork'

from the options menu, rename your clone, choose your repository group

and click 'Fork this Repository.' We recommend this method since is

assures that your clone resides on CWI's Rhodecode server. Now clone

your fork to your local machine. Don't forget to use your fork's url::

    git clone https://guravage@scm.cwi.nl/ITF/cwi-pelican-template-fork cwi

Second, you can clone the template directly to your local machine::

    git clone https://guravage@scm.cwi.nl/ITF/cwi-pelican-template cwi

This clone resides on your local machine. Its origin is read-only, so

you'll have to create a remote repository somewhere and reassign your

clone's origin to point to your new remote repository before you can

push your changes. See the 'Archiving your site' section below for

instructions how to create a remote Rhodecode repository.

Installing the Pelican CWI Theme

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

The cwi project template uses the CWI theme - included in the repository.

Install the theme so Pelican knows where to find it::

    pelican-themes --list -v

Usage

=====

To generate html output, go to the project/cwi directory and invoke

Pelican via make::

    cd cwi/projects/cwi

    make html

Previewing

----------

Pelican has its own built-in server; which you invoke with

make. Better yet, generate and serve the HTML in one command::

    make html serve

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

you browser to the url: http://127.0.0.1:8000/.

Customizing Configuration Settings

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

Pelican has a plethora of setting; all configurable in file named

'pelicanconf.py.' Please refer to `the settings section

<http://docs.getpelican.com/en/3.5.0/settings.html>`_ in the Pelican

documentation.

Here is the contents of pelicanconf.py used in the cwi project

template. Observe that the 'THEME' setting is assigned the string

'cwi'::

    #!/usr/bin/env python

    # -*- coding: utf-8 -*- #

    from __future__ import unicode_literals

    AUTHOR = u'M.A. Guravage'

    SITENAME = u'CWI Pelican Template'

    SITEURL = ''

    PATH = 'content'

    TIMEZONE = 'Europe/Amsterdam'

    DEFAULT_LANG = u'en'

    # Feed generation is usually not desired when developing

    FEED_ALL_ATOM = None

    CATEGORY_FEED_ATOM = None

    TRANSLATION_FEED_ATOM = None

    AUTHOR_FEED_ATOM = None

    AUTHOR_FEED_RSS = None

    # Blogroll

    LINKS = (('Pelican', 'http://getpelican.com/'),

             ('Python.org', 'http://python.org/'),

             ('Jinja2', 'http://jinja.pocoo.org/'),)

    # Social widget

    SOCIAL = (('twitter', 'https://twitter.com/CWInl'),

              ('github', 'http://github.com'),)

    STATIC_PATHS = ['static', 'images', 'extras/.htaccess', 'extras/.htpassword']

    PAGE_PATHS = ['pages','news', 'private']

    ARTICLE_PATHS = ['blog']

    DEFAULT_PAGINATION = 10

    THEME = 'cwi'

    USE_FOLDER_AS_CATEGORY = True

    DISPLAY_CATEGORIES_ON_MENU = False

    DISPLAY_PAGES_ON_MENU = True

    LOAD_CONTENT_CACHE = False

    EXTRA_PATH_METADATA = {

        'extras/.htaccess': {'path': 'pages/.htaccess'},

        'extras/.htpassword': {'path': 'pages/.htpassword'}

        }

    # Uncomment following line if you want document-relative URLs when developing

    #RELATIVE_URLS = True

    # finis

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.' If you forked your clone you already have

a remote repository on CWI's Rhodecode server. Your local clone knows

what its origin is, and you can push your changes directly to it. If,

however, you merely cloned the repository, you must change its origin

to point to a different remote repository before you can push your

changes.  For example, if I had created a new repository at

scm.cwi.nl named itf-pelican-site, I would change the origin of my

local clone with the following command::

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

Afterwards I could push my changes to my remote, whether forked or

new, with the following command::

    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, open a terminal

window, go to the projects directory and invoke 'pelican-quickstart.'

The script will solicit your answers to several 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

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

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

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

You need not change anything here. But if the need arises, here is

where you will affect your changes to the theme::

    ├──  themes

        ├──  cwi

        │   ├──  static

        │   │   ├──  css

        │   │   │   ├──  main.css

        │   │   │   ├──  pygment.css

        │   │   │   ├──  reset.css

        │   │   │   ├──  typogrify.css

        │   │   │   └──  wide.css

        │   │   └──  images

        │   │       └──  icons

        │   │           ├──  aboutme.png

        │   │           ├──  bitbucket.png

        │   │           ├──  cwi.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

        │   └──  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

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

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

documentation. You will find the Pelican documentation at

http://docs.getpelican.com/en/3.5.0/.