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://@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. Customizing Configuration Settings ---------------------------------- Pelican has a plethora of setting; all configurable in file whose default name is '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.' 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 ------------------- 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 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 documentation. You will find the Pelican documentation at http://docs.getpelican.com/en/3.5.0/.