pelican-theme/docs/tips.rst

Tips
####

Here are some tips about Pelican that you might find useful.

Custom 404 Pages
================

When a browser requests a resource that the web server cannot find, the web
server usually displays a generic "File not found" (404) error page that can be
stark and unsightly. One way to provide an error page that matches the theme
of your site is to create a custom 404 page (*not* an article), such as this
Markdown-formatted example stored in ``content/pages/404.md``::

    Title: Not Found
    Status: hidden
    Save_as: 404.html

    The requested item could not be located. Perhaps you might want to check
    the [Archives](/archives.html)?

The next step is to configure your web server to display this custom page
instead of its default 404 page. For Nginx, add the following to your
configuration file's ``location`` block::

    error_page 404 /404.html;

For Apache::

    ErrorDocument 404 /404.html

For Amazon S3, first navigate to the ``Static Site Hosting`` menu in the
bucket settings on your AWS cosole. From there::

    Error Document: 404.html

Publishing to GitHub
====================

`GitHub Pages <https://help.github.com/categories/20/articles>`_ offer an easy
and convenient way to publish Pelican sites. There are `two types of GitHub
Pages <https://help.github.com/articles/user-organization-and-project-pages>`_:
*Project Pages* and *User Pages*. Pelican sites can be published as both
Project Pages and User Pages.

Project Pages
-------------

To publish a Pelican site as a Project Page you need to *push* the content of
the ``output`` dir generated by Pelican to a repository's ``gh-pages`` branch
on GitHub.

The excellent `ghp-import <https://github.com/davisp/ghp-import>`_, which can
be installed with ``pip``, makes this process really easy.

For example, if the source of your Pelican site is contained in a GitHub
repository, and if you want to publish that Pelican site in the form of Project
Pages to this repository, you can then use the following::

    $ pelican content -o output -s pelicanconf.py
    $ ghp-import output
    $ git push origin gh-pages

The ``ghp-import output`` command updates the local ``gh-pages`` branch with
the content of the ``output`` directory (creating the branch if it doesn't
already exist). The ``git push origin gh-pages`` command updates the remote
``gh-pages`` branch, effectively publishing the Pelican site.

.. note::
    The ``github`` target of the Makefile (and the ``gh_pages`` task of the Fabfile)
    created by the ``pelican-quickstart`` command
    publishes the Pelican site as Project Pages, as described above.

.. note:: ghp-import on Windows

    Until `ghp-import Pull Request #25 <https://github.com/davisp/ghp-import/pull/25>`_
    is accepted, you will need to install a custom build of ghp-import:
    ``pip install https://github.com/chevah/ghp-import/archive/win-support.zip``

User Pages
----------

To publish a Pelican site in the form of User Pages, you need to *push* the
content of the ``output`` dir generated by Pelican to the ``master`` branch of
your ``<username>.github.io`` repository on GitHub.

Again, you can take advantage of ``ghp-import``::

    $ pelican content -o output -s pelicanconf.py
    $ ghp-import output
    $ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:master

The ``git push`` command pushes the local ``gh-pages`` branch (freshly updated
by the ``ghp-import`` command) to the ``elemoine.github.io`` repository's
``master`` branch on GitHub.

.. note::

    To publish your Pelican site as User Pages, feel free to adjust the
    ``github`` target of the Makefile.

Custom 404 Pages
----------------

GitHub Pages will display the custom 404 page described above, as noted in the
relevant `GitHub docs <https://help.github.com/articles/custom-404-pages/>`_.

Extra Tips
----------

Tip #1:

To automatically update your Pelican site on each commit, you can create
a post-commit hook. For example, you can add the following to
``.git/hooks/post-commit``::

    pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages

Tip #2:

To use a `custom domain
<https://help.github.com/articles/setting-up-a-custom-domain-with-pages>`_ with
GitHub Pages, you need to put the domain of your site (e.g.,
``blog.example.com``) inside a ``CNAME`` file at the root of your site. To do
this, create the ``content/extra/`` directory and add a ``CNAME`` file to it.
Then use the ``STATIC_PATHS`` setting to tell Pelican to copy this file to your
output directory. For example::

    STATIC_PATHS = ['images', 'extra/CNAME']
    EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},}

Note: use forward slashes, ``/``, even on Windows.

.. hint::
    You can also use the ``EXTRA_PATH_METADATA`` mechanism
    to place a ``favicon.ico`` or ``robots.txt`` at the root of any site.

How to add YouTube or Vimeo Videos
==================================

The easiest way is to paste the embed code of the video from these sites
directly into your source content.

Alternatively, you can also use Pelican plugins like ``liquid_tags``,
``pelican_youtube``, or ``pelican_vimeo`` to embed videos in your content.

Moreover, markup languages like reST and Markdown have plugins that let you
embed videos in the markup. You can use `reST video directive
<https://gist.github.com/dbrgn/2922648>`_ for reST or `mdx_video plugin
<https://github.com/italomaia/mdx-video>`_ for Markdown.