try pelican

try pelican

I just forget the usage again and again,so I decided to WcRoIpTyE it=.=

getting start


Pelican currently runs best on Python 2.7.x and 3.3+; earlier versions of Python are not supported.

You can install Pelican via several different methods. The simplest is via pip:

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


pip install --upgrade pelican

kickstart your site

├── content
   └── (pages)
├── output
├── Makefile
├──       # Main settings file
└──       # Settings to use when ready to publish

writing content

articles and pages

Pelican considers “articles” to be chronological content, such as posts on a blog, and thus associated with a date.

The idea behind “pages” is that they are usually not temporal in nature and are used for content that does not change very often.

file metadata

Pelican tries to be smart enough to get the information it needs from the file system (for instance, about the category of your articles), but some information you need to provide in the form of metadata inside your files.

Metadata syntax for Markdown posts should follow this pattern:

Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds

This is the content of my super blog post.


If you create a folder named pages inside the content folder, all the files in it will be used to generate static pages, such as About or Contact pages. (See example filesystem layout below.)

You can use the DISPLAY_PAGES_ON_MENU setting to control whether all those pages are displayed in the primary navigation menu. (Default is True.)

If you want to exclude any pages from being linked to or listed in the menu then add a status: hidden attribute to its metadata. This is useful for things like making error pages that fit the generated theme of your site.

linking to internal content

it's useful i think

From Pelican 3.1 onwards, it is now possible to specify intra-site links to files in the source content hierarchy instead of files in the generated hierarchy. This makes it easier to link from the current post to other content that may be sitting alongside that post (instead of having to determine where the other content will be placed after site generation).

To link to internal content (files in the content directory), use the following syntax for the link target: {filename}path/to/file Note: forward slashes, /, are the required path separator in the {filename} directive on all operating systems, including Windows.

linking to static files

Linking to non-article or non-page content uses the same {filename} syntax as described above. It is important to remember that those files will not be copied to the output directory unless the source directories containing them are included in the STATIC_PATHS setting of the project’s file. Pelican’s default configuration includes the images directory for this, but others must be added manually. Forgetting to do so will result in broken links.

mixed content in the same directory

Starting with Pelican 3.5, static files can safely share a source directory with page source files, without exposing the page sources in the generated site. Any such directory must be added to both STATIC_PATHS and PAGE_PATHS (or STATIC_PATHS and ARTICLE_PATHS). Pelican will identify and process the page source files normally, and copy the remaining files as if they lived in a separate directory reserved for static files.

Note: Placing static and content source files together in the same source directory does not guarantee that they will end up in the same place in the generated site. The easiest way to do this is by using the {attach} link syntax (described below). Alternatively, the STATIC_SAVE_AS, PAGE_SAVE_AS, and ARTICLE_SAVE_AS settings (and the corresponding *_URL settings) can be configured to place files of different types together, just as they could in earlier versions of Pelican.

attaching static files

Starting with Pelican 3.5, static files can be “attached” to a page or article using this syntax for the link target: {attach}path/to/file This works like the {filename} syntax, but also relocates the static file into the linking document’s output directory. If the static file originates from a subdirectory beneath the linking document’s source, that relationship will be preserved on output. Otherwise, it will become a sibling of the linking document.

This only works for linking to static files, and only when they originate from a directory included in the STATIC_PATHS setting.

linking to authors,categories,index and tags

You can link to authors, categories, index and tags using the {author}name, {category}foobar, {index} and {tag}tagname syntax.

deprecated internal link syntax

To remain compatible with earlier versions, Pelican still supports vertical bars (||) in addition to curly braces ({}) for internal links. For example: |filename|an_article.rst, |tag|tagname, |category|foobar. The syntax was changed from || to {} to avoid collision with Markdown extensions or reST directives. Support for the old syntax may eventually be removed.

importing an existing site

It is possible to import your site from WordPress, Tumblr, Dotclear, and RSS feeds using a simple script. See Importing an existing site.


syntax highlighting

publishing drafts

publish your site

site generation

Once Pelican is installed and you have some content (e.g., in Markdown or reST format), you can convert your content into HTML via the pelican command, specifying the path to your content and (optionally) the path to your settings file:

pelican /path/to/your/content/ [-s path/to/your/]

The above command will generate your site and save it in the output/ folder, using the default theme to produce a simple site. The default theme consists of very simple HTML without styling and is provided so folks may use it as a basis for creating their own themes.

When working on a single article or page, it is possible to generate only the file that corresponds to that content. To do this, use the --write-selected argument, like so:

pelican --write-selected output/posts/my-post-title.html

Note that you must specify the path to the generated output file — not the source content. To determine the output file name and location, use the --debug flag. If desired, --write-selected can take a comma-separated list of paths or can be configured as a setting. (See: Writing only selected content)

Pelican has other command-line switches available. Have a look at the help to see all the options you can use:

pelican --help

viewing the generated files

The files generated by Pelican are static files, so you don’t actually need anything special to view them. You can use your browser to open the generated HTML files directly:

firefox output/index.html

Because the above method may have trouble locating your CSS and other linked assets, running a simple web server using Python will often provide a more reliable previewing experience.

For Python 2, run:

cd output
python -m SimpleHTTPServer

For Python 3,run:

cd output
python -m http.server

Once the basic server has been started, you can preview your site at http://localhost:8000/


After you have generated your site, previewed it in your local development environment, and are ready to deploy it to production, you might first re-generate your site with any production-specific settings (e.g., analytics feeds, etc.) that you may have defined:

pelican content -s

To base your publish configuration on top of your, you can import your pelicanconf settings by including the following line in your

from pelicanconf import *

If you have generated a using pelican-quickstart, this line is included by default.

The steps for deploying your site will depend on where it will be hosted. If you have SSH access to a server running Nginx or Apache, you might use the rsync tool to transmit your site files:

rsync -avc --delete output/

There are many other deployment options, some of which can be configured when first setting up your site via the pelican-quickstart command. See the Tips page for detail on publishing via GitHub Pages.


While the pelican command is the canonical way to generate your site, automation tools can be used to streamline the generation and publication flow. One of the questions asked during the pelican-quickstart process pertains to whether you want to automate site generation and publication. If you answered “yes” to that question, a and Makefile will be generated in the root of your project. These files, pre-populated with certain information gleaned from other answers provided during the pelican-quickstart process, are meant as a starting point and should be customized to fit your particular needs and usage patterns. If you find one or both of these automation tools to be of limited utility, these files can deleted at any time and will not affect usage of the canonical pelican command.

Following are automation tools that “wrap” the pelican command and can simplify the process of generating, previewing, and uploading your site.


The advantage of Invoke is that it is written in Python and thus can be used in a wide range of environments. The downside is that it must be installed separately. Use the following command to install Invoke, prefixing with sudo if your environment requires it:

pip install invoke

Take a moment to open the file that was generated in your project root. You will see a number of commands, any one of which can be renamed, removed, and/or customized to your liking. Using the out-of-the-box configuration, you can generate your site via:

invoke build

If you’d prefer to have Pelican automatically regenerate your site every time a change is detected (which is handy when testing locally), use the following command instead:

invoke regenerate

To serve the generated site so it can be previewed in your browser at http://localhost:8000/:

invoke serve

If during the pelican-quickstart process you answered “yes” when asked whether you want to upload your site via SSH, you can use the following command to publish your site via rsync over SSH:

invoke publish

These are just a few of the commands available by default, so feel free to explore and see what other commands are available. More importantly, don’t hesitate to customize to suit your specific needs and preferences.


A Makefile is also automatically created for you when you say “yes” to the relevant question during the pelican-quickstart process. The advantage of this method is that the make command is built into most POSIX systems and thus doesn’t require installing anything else in order to use it. The downside is that non-POSIX systems (e.g., Windows) do not include make, and installing it on those systems can be a non-trivial task.

If you want to use make to generate your site using the settings in, run:

make html

To generate the site for production, using the settings in, run:

make publish

If you’d prefer to have Pelican automatically regenerate your site every time a change is detected (which is handy when testing locally), use the following command instead:

make regenerate

To serve the generated site so it can be previewed in your browser at http://localhost:8000/:

make serve

Normally you would need to run make regenerate and make serve in two separate terminal sessions, but you can run both at once via:

make devserver

The above command will simultaneously run Pelican in regeneration mode as well as serve the output at http://localhost:8000.

When you’re ready to publish your site, you can upload it via the method(s) you chose during the pelican-quickstart questionnaire. For this example, we’ll use rsync over ssh:

make rsync_upload

(The default Makefile and scripts use the python and pelican executables to complete its tasks. If you want to use different executables, such as python3, you can set the PY and PELICAN environment variables, respectively, to override the default executable names.)