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, such as this Markdown-formatted example:: 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 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 Windows Until `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 ``.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.