forked from github/pelican
332 lines
15 KiB
ReStructuredText
332 lines
15 KiB
ReStructuredText
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 console. From there::
|
|
|
|
Error Document: 404.html
|
|
|
|
Publishing to GitHub Pages
|
|
==========================
|
|
|
|
If you use `GitHub <https://github.com/>`_ for your Pelican site you can
|
|
publish your site to `GitHub Pages <https://pages.github.com/>`_ for free.
|
|
Your site will be published to ``https://<username>.github.io`` if it's a user or
|
|
organization site or to ``https://<username>.github.io/<repository>`` if it's a
|
|
project site. It's also possible to `use a custom domain with GitHub Pages <https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site>`_.
|
|
|
|
There are `two ways to publish a site to GitHub Pages <https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site>`_:
|
|
|
|
1. **Publishing from a branch:** run ``pelican`` locally and push the output
|
|
directory to a special branch of your GitHub repo. GitHub will then publish
|
|
the contents of this branch to your GitHub Pages site.
|
|
2. **Publishing with a custom GitHub Actions workflow:** just push the source
|
|
files of your Pelican site to your GitHub repo's default branch and have a
|
|
custom GitHub Actions workflow run ``pelican`` for you to generate the
|
|
output directory and publish it to your GitHub Pages site. This way you
|
|
don't need to run ``pelican`` locally. You can even edit your site's source
|
|
files using GitHub's web interface and any changes that you commit will be
|
|
published.
|
|
|
|
Publishing a Project Site to GitHub Pages from a Branch
|
|
-------------------------------------------------------
|
|
|
|
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 -b gh-pages
|
|
$ 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
|
|
``tasks.py``) created by the ``pelican-quickstart`` command publishes the
|
|
Pelican site as Project Pages, as described above.
|
|
|
|
Publishing a User Site to GitHub Pages from a Branch
|
|
----------------------------------------------------
|
|
|
|
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 -b gh-pages
|
|
$ 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.
|
|
|
|
Another option for publishing to User Pages is to generate the output files in
|
|
the root directory of the project.
|
|
|
|
For example, your main project folder is ``<username>.github.io`` and you can
|
|
create the Pelican project in a subdirectory called ``Pelican``. Then from
|
|
inside the ``Pelican`` folder you can run::
|
|
|
|
$ pelican content -o .. -s pelicanconf.py
|
|
|
|
Now you can push the whole project ``<username>.github.io`` to the master
|
|
branch of your GitHub repository::
|
|
|
|
$ git push origin master
|
|
|
|
(assuming origin is set to your remote repository).
|
|
|
|
Publishing to GitHub Pages Using a Custom GitHub Actions Workflow
|
|
-----------------------------------------------------------------
|
|
|
|
Pelican-powered sites can be published to GitHub Pages via a `custom workflow
|
|
<https://github.com/getpelican/pelican/blob/master/.github/workflows/github_pages.yml>`_.
|
|
To use it:
|
|
|
|
1. Enable GitHub Pages in your repo: go to **Settings → Pages** and choose
|
|
**GitHub Actions** for the **Source** setting.
|
|
|
|
2. Commit a ``.github/workflows/pelican.yml`` file to your repo with these contents:
|
|
|
|
.. code-block:: yaml
|
|
|
|
name: Deploy to GitHub Pages
|
|
on:
|
|
push:
|
|
branches: ["main"]
|
|
workflow_dispatch:
|
|
jobs:
|
|
deploy:
|
|
uses: "getpelican/pelican/.github/workflows/github_pages.yml@master"
|
|
permissions:
|
|
contents: "read"
|
|
pages: "write"
|
|
id-token: "write"
|
|
with:
|
|
settings: "publishconf.py"
|
|
|
|
You may want to replace the ``@master`` with the ID of a specific commit in
|
|
this repo in order to pin the version of the reusable workflow that you're using:
|
|
``uses: getpelican/pelican/.github/workflows/github_pages.yml@<COMMIT_ID>``.
|
|
If you do this you might want to get Dependabot to send you automated pull
|
|
requests to update that commit ID whenever new versions of this workflow are
|
|
published, like so:
|
|
|
|
.. code-block:: yaml
|
|
|
|
# .github/dependabot.yml
|
|
version: 2
|
|
updates:
|
|
- package-ecosystem: "github-actions"
|
|
directory: "/"
|
|
schedule:
|
|
interval: "monthly"
|
|
|
|
See `GitHub's docs about using Dependabot to keep your actions up to date <https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot>`_.
|
|
|
|
3. Go to the **Actions** tab in your repo
|
|
(``https://github.com/<username>/<repository>/actions``) and you should see a
|
|
**Deploy to GitHub Pages** action running.
|
|
|
|
4. Once the action completes you should see your Pelican site deployed at your
|
|
repo's GitHub Pages URL: ``https://<username>.github.io`` for a user or
|
|
organization site or ``https://<username>.github.io/<repository>>`` for a
|
|
project site.
|
|
|
|
Notes:
|
|
|
|
* You don't need to set ``SITEURL`` or ``FEED_DOMAIN`` in your Pelican
|
|
settings: the workflow will set them correctly for you
|
|
|
|
* You don't need to commit your ``--output`` / ``OUTPUT_PATH`` directory
|
|
(``output/``) to git: the workflow will run ``pelican`` to build the output
|
|
directory for you on GitHub Actions
|
|
|
|
See `GitHub's docs about reusable workflows <https://docs.github.com/en/actions/using-workflows/reusing-workflows>`_
|
|
for more information.
|
|
|
|
A number of optional inputs can be added to the ``with:`` block when calling
|
|
the workflow, for example:
|
|
|
|
.. code-block:: yaml
|
|
|
|
with:
|
|
settings: "publishconf.py"
|
|
requirements: "pelican[markdown] typogrify"
|
|
theme: "https://github.com/seanh/sidecar.git"
|
|
python: "3.12"
|
|
|
|
Here's the complete list of workflow inputs:
|
|
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
| Name | Required | Description | Type | Default |
|
|
+==================+==========+============================================+========+===============+
|
|
| ``settings`` | Yes | The path to your Pelican settings | string | |
|
|
| | | file (``pelican``'s | | |
|
|
| | | ``--settings`` option), | | |
|
|
| | | for example: ``"publishconf.py"`` | | |
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
| ``requirements`` | No | The Python requirements to | string | ``"pelican"`` |
|
|
| | | install, for example to enable | | |
|
|
| | | markdown and typogrify use: | | |
|
|
| | | ``"pelican[markdown] typogrify"`` | | |
|
|
| | | or if you have a requirements | | |
|
|
| | | file: ``"-r requirements.txt"`` | | |
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
| ``output-path`` | No | Where to output the generated | string | ``"output/"`` |
|
|
| | | files (``pelican``'s ``--output`` | | |
|
|
| | | option) | | |
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
| ``theme`` | No | The GitHub repo URL of a custom | string | ``""`` |
|
|
| | | theme to use, for example: | | |
|
|
| | | ``"https://github.com/seanh/sidecar.git"`` | | |
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
| ``python`` | No | The version of Python to use to build the | string | ``"3.12"`` |
|
|
| | | site, for example: ``"3.12"`` (to use the | | |
|
|
| | | most recent version of Python 3.12, this | | |
|
|
| | | is faster) or ``"3.12.1"`` (to use an | | |
|
|
| | | exact version, slower) | | |
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
| ``siteurl`` | No | The base URL of your web site (Pelican's | string | The URL of |
|
|
| | | ``SITEURL`` setting). If not passed this | | your GitHub |
|
|
| | | will default to the URL of your GitHub | | Pages site. |
|
|
| | | Pages site, which is correct in most | | |
|
|
| | | cases. | | |
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
| ``feed_domain`` | No | The domain to be prepended to feed URLs | string | The URL of |
|
|
| | | (Pelican's ``FEED_DOMAIN`` setting). If | | your GitHub |
|
|
| | | not passed this will default to the URL of | | Pages site. |
|
|
| | | your GitHub Pages site, which is correct | | |
|
|
| | | in most cases. | | |
|
|
+------------------+----------+--------------------------------------------+--------+---------------+
|
|
|
|
|
|
"Insecure content" warnings from browsers
|
|
"""""""""""""""""""""""""""""""""""""""""
|
|
|
|
If your site uses ``https://`` and is broken because the browser is blocking
|
|
network requests (for example for CSS files) due to "insecure content" this
|
|
may be because GitHub Pages is generating ``http://`` URLs for your site.
|
|
|
|
To fix this go into your site repo's settings and enable the **Enforce HTTPS** setting:
|
|
go to **Settings → Pages** and check **Enforce HTTPS**.
|
|
Then re-run the workflow to re-deploy your site.
|
|
Alternatively, you can use the workflow's ``siteurl`` and ``feed_domain`` settings.
|
|
|
|
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/>`_.
|
|
|
|
Update your site on each commit
|
|
-------------------------------
|
|
|
|
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
|
|
|
|
Copy static files to the root of your site
|
|
------------------------------------------
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
Develop Locally Using SSL
|
|
==================================
|
|
|
|
Here's how you can set up your local pelican server to support SSL.
|
|
|
|
First, create a self-signed certificate and key using ``openssl`` (this creates ``cert.pem`` and ``key.pem``)::
|
|
|
|
$ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
|
|
|
|
And use this command to launch the server (the server starts within your ``output`` directory)::
|
|
|
|
python -m pelican.server 8443 --key=../key.pem --cert=../cert.pem
|
|
|
|
If you are using ``develop-server.sh``, add this to the top::
|
|
|
|
CERT="$BASEDIR/cert.pem"
|
|
KEY="$BASEDIR/key.pem"
|
|
|
|
and modify the ``pelican.server`` line as follows::
|
|
|
|
$PY -m pelican.server $port --ssl --cert="$CERT" --key="$KEY" &
|