diff --git a/README.txt b/README.txt index b226837b1f4b0bfb3c6afdb72518388acfd19c2e..6da827cd9690d4661f06aca818faf12ebde7651c 100644 --- a/README.txt +++ b/README.txt @@ -3,8 +3,12 @@ Introduction Pelican is a static site generator, written in Python. -This repository contains a Pelican project and theme you can use as a -foundation on which to build your own static HTML website. +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 @@ -15,8 +19,8 @@ environment. You can create a virtual environment à la carte with virtualenv, or manage several virtual environments under a single directory with virtualenvwrapper:: - virtualenv pelican - cd pelican + virtualenv cwi-pelican + cd cwi-pelican . ./bin/activate Once the virtual environment has been created and activated, use pip @@ -35,21 +39,22 @@ first the requisite Typogrify library must be installed:: Installing Pelican project template -=================================== +----------------------------------- -To kick start your website development we have created a Pelican theme -and project template with example content. While you can install the -template anywhere you like, for this example, clone the -cwi-pelican-template in the root of your Pelican virtual -environment. Don't forget to use your own username in the url:: +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 Pelican CWI project uses the corresponding CWI theme, but it must +The cwi project template uses a corresponding CWI theme, but it must be installed before Pelican can use it:: pelican-theme --symlink ${PWD}/cwi/theme/cwi @@ -62,3 +67,229 @@ 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 anad SSH_Target_DIR. + + +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 +com/en/3.5.0.