2016年5月22日日曜日

How to make the page-centered site by Pelican

Pelican is a static site generator written in Python. It has two main types of content: the article and the page. The article is a blog post. The page is a non-chronological content and usually written as a part of the site in advance, e.g. like “About” or “Contact” pages.

Pelican is mainly intended for an article-centered site, that is a blog. Its default settings and themes are suitable for the blogs. If you want to make a page-centered site instead of a blog, you must change some settings and customize templates of your theme.


1. Make a source directory be page-centered


[Before changes (default)]
yourproject/
    ├── content/
    │   └──  pages/
    │       ├── yourpage.md
    │       └──  ...
    └── output/
          └──  pages/
              ├── yourpage.html
              └──  ...

To make a source directory be page-centered, add the following two lines in the pelicanconf.py:
PAGE_PATHS = ['']
ARTICLE_PATHS = ['articles']

[After changes]
yourproject/
    ├── content/
    │   ├── yourpage.md
    │   └──  ...
    └── output/
          ├── yourpage.html
          └──  ...

You can put page sources in content directory instead of content/pages directory.
You can use your favorite name for articles directory instead of "articles".

If you want to make blog posts in addition to pages, add the following lines in pelicanconf.py:
PAGE_PATHS = ['']
ARTICLE_PATHS = ['articles']
ARTICLE_URL = 'articles/{slug}.html'
ARTICLE_SAVE_AS = 'articles/{slug}.html'
TAG_URL = 'articles/tag/{slug}.html'
TAG_SAVE_AS = 'articles/tag/{slug}.html'
CATEGORY_URL = 'articles/category/{slug}.html'
CATEGORY_SAVE_AS = 'articles/category/{slug}.html'
AUTHOR_URL = 'articles/author/{slug}.html'
AUTHOR_SAVE_AS = 'articles/author/{slug}.html'
(...etc.)
In publishconf.py (if you need RSS output):
FEED_ALL_ATOM = 'articles/feeds/all.atom.xml'
CATEGORY_FEED_ATOM = 'articles/feeds/%s.atom.xml'

[After changes]
yourproject/
    ├── content/
    │   ├── yourpage.md
    │   ├──  ...
    │   └──  articles/
    │       └──  yourblogpost.md
    └── output/
          ├── yourpage.html
          ├──  ...
          └── articles/
              ├── yourblogpost.html
              ├── tag/
              ├── category/
              ├── author/
              └── feeds/


2. Make a source directory structure be kept in html output


[Before changes (default)]
yourproject/
    ├── content/
    │   ├── yourpage1.md
    │   └── dir1/
    │       ├── yourpage2.md
    │       └──  dir2/
    │           └── yourpage3.md
    └── output/
          ├── yourpage1.html
          ├── yourpage2.html
          └── yourpage3.html

To make a source directory structure be kept in html output, add the following lines in pelicanconf.py:
PATH_METADATA = '(?P<path_no_ext>.*)\..*'
PAGE_SAVE_AS = '{path_no_ext}.html'
PAGE_URL = '{path_no_ext}.html'

[After changes]
yourproject/
    ├── content/
    │   ├── yourpage1.md
    │   └── dir1/
    │       ├── yourpage2.md
    │       └──  dir2/
    │           └── yourpage3.md
    └── output/
           ├── yourpage1.html
           └── dir1/
               ├── yourpage2.html
               └──  dir2/
                   └── yourpage3.html

You can keep the hierarchic structure in html output as in content directory.
ref. https://github.com/getpelican/pelican/issues/686


3. Make blog related files be not generated


[Before changes (default)]
yourproject/
    ├── content/
    │   └── yourpage.md
    └── output/
          ├── yourpage.html
          ├── index.html
          ├── tags.html
          ├── categories.html
          ├── authors.html
          └── archives.html

To make blog related files be not generated, add the following lines in pelicanconf.py:
DIRECT_TEMPLATES = []

[After changes]
yourproject/
    ├── content/
    │   └── yourpage.md
    └── output/
          └── yourpage.html

Blog related filles (index.html, tags.html, categories.html, authors.html, archives.html) are not generated.
But you must write your "index.html" file yourself instead.

If you want to make blog posts in addition to pages and need blog related files, add the following lines in pelicanconf.py:
DIRECT_TEMPLATES = ['index', 'tags', 'categories', 'authors', 'archives']
INDEX_SAVE_AS = 'articles/index.html'
TAGS_SAVE_AS = 'articles/tags.html'
CATEGORIES_SAVE_AS = 'articles/categories.html'
AUTHORS_SAVE_AS = 'articles/authors.html'
ARCHIVES_SAVE_AS = 'articles/archives.html'

[After changes]
yourproject/
    ├── content/
    │   ├── yourpage.md
    │   └── articles/
    │       └── yourblogpost.md
    └── output/
          ├── yourpage.html
          └── articles/
              ├── yourblogpost.html
              ├── index.html
              ├── tags.html
              ├── categories.html
              ├── authors.html
              └── archives.html

4. Make pages and categories be not displayed on the global menu of the template


In pelicanconf.py:
DISPLAY_PAGES_ON_MENU = False
DISPLAY_CATEGORIES_ON_MENU = False

You must write the global menu yourself instead. In default template, you can this by writing MENUITEMS setting.

In pelicanconf.py:
MENUITEMS = [('Menu1', 'dir1/index.html'), ('Menu2', 'dir2/index.html'), ('Contact', 'contact.html'), ('About', 'about.html')]

5. Assign custom templates on a per-page basis (if you need)


In source file's metadata:
Template: template_name

If you use reST format, in source file's metadata:
:template: template_name

You must make your theme contains the relevant template file (e.g. template_name.html).

ref. http://docs.getpelican.com/en/3.6.3/faq.html#how-do-i-assign-custom-templates-on-a-per-page-basis