forked from github/pelican
101 lines
3.7 KiB
ReStructuredText
101 lines
3.7 KiB
ReStructuredText
Tips
|
|
####
|
|
|
|
Here are some tips about Pelican that you might find useful.
|
|
|
|
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 ``easy_install`` or ``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 created by the ``pelican-quickstart``
|
|
command publishes the Pelican site as Project Pages, as described above.
|
|
|
|
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.
|
|
|
|
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/extras/`` 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'},}
|
|
|
|
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.
|