1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
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 -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.
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 -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).
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" &
|
