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 offer an easy and convenient way to publish Pelican
sites. There are two types of GitHub 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, 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 WindowsUntil ghp-import Pull Request #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.


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 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
for reST or mdx_video plugin for Markdown.
