-
Notifications
You must be signed in to change notification settings - Fork 0
/
setting-up-a-github-blog-with-pelican.html
executable file
·288 lines (235 loc) · 18.5 KB
/
setting-up-a-github-blog-with-pelican.html
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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
<!doctype html>
<html lang="en" itemscope itemtype="http://schema.org/Person">
<head>
<meta charset="utf-8">
<!-- Site Meta Data -->
<title>Setting up a GitHub blog with Pelican</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="author" content="Pascal Rabier">
<link rel="shortcut icon" href="">
<!-- schema.org -->
<meta itemprop="name" content="Software-Defined Infra Blog">
<meta itemprop="image" content="">
<meta itemprop="description" content="">
<link href='https://fonts.googleapis.com/css?family=Open+Sans:400,600,700' rel='stylesheet' type='text/css'>
<!-- Style Meta Data -->
<link rel="stylesheet" href="https://rabierp.github.io/theme/css/style.css" type="text/css" />
<link rel="stylesheet" href="https://rabierp.github.io/theme/css/pygments.css" type="text/css" />
<!-- Feed Meta Data -->
<link href="https://rabierp.github.io/feeds/all.atom.xml" type="application/atom+xml" rel="alternate" title="Software-Defined Infra Blog ATOM Feed" />
<!-- Twitter Feed -->
<meta name="twitter:card" content="summary">
<meta name="twitter:site" content="@SWDefinedInfra">
<meta name="twitter:image" content="">
<meta name="twitter:creator" content="@SWDefinedInfra">
<meta name="twitter:url" content="https://rabierp.github.io/setting-up-a-github-blog-with-pelican.html">
<meta name="twitter:title" content="Software-Defined Infra Blog ~ Setting up a GitHub blog with Pelican">
<meta name="twitter:description" content="I've been thinking about writing my own Blog for a long time, but had not found the time to invest into searching the simple and fun kind of solution I was looking for. Not being a developer, I only discovered very recently that GitHub is offering a free way of …">
<!-- Facebook Meta Data -->
<meta property="og:title" content="Software-Defined Infra Blog ~ Setting up a GitHub blog with Pelican" />
<meta property="og:description" content="I've been thinking about writing my own Blog for a long time, but had not found the time to invest into searching the simple and fun kind of solution I was looking for. Not being a developer, I only discovered very recently that GitHub is offering a free way of …" />
<meta property="og:image" content="" />
</head>
<body>
<!-- Sidebar -->
<aside>
<!--<center><a href="https://rabierp.github.io"><img id="avatar" src=""></a></center>-->
<h1>Software-Defined Infra Blog</h1>
<p>Cloud Infrastructure & Architecture</p>
<br>
<a class="twitter-follow-button"
href="https://twitter.com/@SWDefinedInfra"
data-show-count="false"
data-lang="en">
Follow @twitterdev
</a>
<script type="text/javascript">
window.twttr = (function (d, s, id) {
var t, js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); js.id = id;
js.src= "https://platform.twitter.com/widgets.js";
fjs.parentNode.insertBefore(js, fjs);
return window.twttr || (t = { _e: [], ready: function (f) { t._e.push(f) } });
}(document, "script", "twitter-wjs"));
</script>
<nav class="nav">
<ul class="list-bare">
<li><a class="nav__link" href="https://rabierp.github.io">Blog</a></li>
<li><a class="nav__link" href="https://rabierp.github.io/pages/about.html">About</a></li>
</ul>
</nav>
<p class="social">
<a href="https://www.linkedin.com/in/pascalrabier" target="_blank" ><img src="https://rabierp.github.io/theme/images/icons/linkedin.png"></a>
<a href="https://github.com/rabierp" target="_blank" ><img src="https://rabierp.github.io/theme/images/icons/github.png"></a>
<a href="https://twitter.com/SWDefinedInfra" target="_blank" ><img src="https://rabierp.github.io/theme/images/icons/twitter.png"></a>
<a href="https://rabierp.github.io/feeds/all.atom.xml" rel="alternate">
<img src="https://rabierp.github.io/theme/images/icons/rss.png"></a>
</p>
<h2>Categories</h2>
<ul class="navbar">
<li class="active"><a href="https://rabierp.github.io/category/blogging.html">Blogging</a></li>
</ul>
<h2 class="blog_roll_link"><br/>BLOGROLLS</h2>
<ul class="navbar">
<li><a href="http://getpelican.com/">Pelican</a></li>
<li><a href="http://python.org/">Python.org</a></li>
<li><a href="http://jinja.pocoo.org/">Jinja2</a></li>
</ul>
</aside>
<!-- Content -->
<article>
<section id="content">
<article>
<h2 class="post_title post_detail"><a href="https://rabierp.github.io/setting-up-a-github-blog-with-pelican.html" rel="bookmark" title="Permalink to Setting up a GitHub blog with Pelican">Setting up a GitHub blog with Pelican</a></h2>
<div class="entry-content blog-post">
<p>I've been thinking about writing my own Blog for a long time, but had not found the time to invest into searching the simple and fun kind of solution I was looking for.
Not being a developer, I only discovered very recently that GitHub is offering a free way of hosting your own static blog.
I was quickly interested, and a few minutes googling pointed me to <a href="http://jekyllrb.com">Jekyllrb</a> as the natural tool to build my static site and have it hosted as a GitHub user page.
But I was not fully convinced at start because I wasn't willing to invest in learning Ruby. So it took me a bit more googling to find <a href="http://getpelican.com">pelican</a>, which is a <a href="http://python.org">Python</a> tool, a language I'm more comfortable with.</p>
<p>Here's how I have set up Pelican in order to be able to publish my Blog on My GitHub User Page:</p>
<h3>Setup your User Page repo on GitHub</h3>
<p>Simply create a new GitHub repository named <code><github-username>.github.io</code>.
You can follow the instructions <a href="https://pages.github.com">here</a>.</p>
<p>Then, clone this empty repo to the local machine:</p>
<div class="highlight"><pre><span></span>$ git clone https://github.com/<github-username>/<github-username>.github.io/
$ <span class="nb">cd</span> <github-username>.github.io
</pre></div>
<p>We now are working on the <code>master</code> branch of the local repo.</p>
<p>But, since the kind of page we want to publish is a <em>User</em> page, rather than a <em>Project</em> page, the master branch of the repo is the one who must directly handle the root of our future website, not the pelican files that will be installed in the next following steps.</p>
<p>So, create directly a new branch, that I choose to name <code>pelican</code>, because it will handle the pelican project files:</p>
<div class="highlight"><pre><span></span>$ git checkout -b pelican
</pre></div>
<h3>Install & Setup Pelican on your PC</h3>
<p>I'm Assuming you already have Python installed (As of today, Pelican works as nicely with Python 2.7.x as with 3.3+).
If this is not the case and if you're working on WindowsTM, I recommend using <a href="http://chocolatey.org">Chocolatey</a>, my favorite Package Manager for that OS, to easily install Python and any kind of free software you like (or mostly any, since the chocolatey package repository is pretty large!).</p>
<p>Now, let's install the Pelican, Markdown and ghp-import Python modules:</p>
<div class="highlight"><pre><span></span>$ pip install pelican markdown ghp-import
</pre></div>
<p>In addition to Pelican:</p>
<ul>
<li><a href="http://whatismarkdown.com">Markdown</a> is a popular lightweight markup languages well suited for web content</li>
<li><a href="https://github.com/davisp/ghp-import">ghp-import</a> will be used later to publish the blog to the target GitHub Page</li>
</ul>
<p>Let's configure Pelican:</p>
<div class="highlight"><pre><span></span>$ pelican-quickstart
</pre></div>
<p>Basically, you can keep all the default parameters, except of course for:</p>
<ul>
<li>Title of the Web site: choose your title</li>
<li>Author of the Web site: put your name or pseudo depending on your preferences</li>
<li>URL prefix: answer 'Y' and specify the GitHub User page URL 'http://<github-username>.github.io/'</li>
</ul>
<p>As a result, the <code>MyBlog</code> directory now contains the Pelican default file tree.</p>
<p>The <a href="http://docs.getpelican.com">Pelican documentation</a> will give you more insights on all possible parameters.</p>
<h3>Create a first Article & locally Preview your Blog</h3>
<p>All you have to do, is to go to the <code>content</code> directory in the hierarchy create in the previous paragraph, and create the file that will contain your first Post.</p>
<p>You can name the file as you want, e.g. <code>My-1st-post.md</code>.</p>
<p>File content format is:</p>
<ul>
<li>the header, with the following lines: 'Title: <em>Post title</em>', 'Date: <em>Post date</em>', 'Category: <em>Post category</em>' and 'Tags: <em>list of coma separated Post tags</em>',</li>
<li>the content, written by default in reStructuredText (aka rst) or in Markdown markup languages.</li>
</ul>
<p>I prefer using Markdown rather than Pelican's default rst, that's why I added mardown module to the <code>pip install</code> command detailed earlier in this article.</p>
<p>Here is an example article file in Markdown, borrowed from the Pelican documentation:</p>
<div class="highlight"><pre><span></span><span class="n">Title</span><span class="o">:</span> <span class="n">My</span> <span class="n">first</span> <span class="n">review</span>
<span class="n">Date</span><span class="o">:</span> <span class="mi">2010</span><span class="o">-</span><span class="mi">12</span><span class="o">-</span><span class="mi">03</span> <span class="mi">10</span><span class="o">:</span><span class="mi">20</span>
<span class="n">Category</span><span class="o">:</span> <span class="n">Review</span>
<span class="err">#</span> <span class="n">Product</span> <span class="n">of</span> <span class="n">the</span> <span class="n">Year</span> <span class="n">Review</span><span class="o">!</span>
<span class="n">This</span> <span class="k">is</span> <span class="n">an</span> <span class="o">**</span><span class="n">Awesome</span><span class="o">**</span> <span class="n">product</span>
</pre></div>
<p>You might find GitHub's <a href="https://guides.github.com/features/mastering-markdown">Markdown Guide</a> helpful.</p>
<p>Now, from the project main directory, run pelican to generate the static html content and then launch a local webserver:</p>
<div class="highlight"><pre><span></span>$ pelican content
$ python -m pelican.server
</pre></div>
<p>Alternatively, there's another possible way to launch the local webserver by using the pelican provided script:</p>
<div class="highlight"><pre><span></span>$ ./development_server.sh start
</pre></div>
<p>(but in my case, on Windows and from GitBash, I had to create a symlink from <code>python.exe</code> to <code>python3.exe</code> to make it work)</p>
<p>Now, check the result by opening a browser at <a href="http://localhost:8000">http://localhost:8000</a>.</p>
<h3>Install & Setup a Theme (Optional)</h3>
<p>Now we have a first start for the content, it's time to work on the presentation.
It's of course possible to design your very own presentation by developing your own theme, but it is by far easier to start by reusing existing ones: Pelican has a fair amount of themes you can discover & download <a href="http://www.pelicanthemes.com">here</a>.
I choose <code>pelican-blue</code> and cloned it from the project's GitHub <a href="https://github.com/Parbhat/pelican-blue">repository</a>.</p>
<p>For this, I'd recommend creating a <code>pelican-themes</code> directory in your pelican project dir:</p>
<div class="highlight"><pre><span></span>$ mkdir pelican-themes
$ <span class="nb">cd</span> pelican-themes
$ git clone https://github.com/Parbhat/pelican-blue.git
</pre></div>
<p>Then, import the theme into your Pelican config:</p>
<div class="highlight"><pre><span></span>$ <span class="nb">cd</span> ..
$ pelican-themes -i pelican-themes/pelican-blue
</pre></div>
<p>No sure for each theme you might like & use, but in my case, the GitHUb repo <code>Readme.md</code> file described variables to be setup in the <code>pelicanconf.py</code> file:</p>
<div class="highlight"><pre><span></span>THEME = 'path-to-pelican-blue-theme'
SIDEBAR_DIGEST = 'Programmer and Web Developer'
FAVICON = 'url-to-favicon'
DISPLAY_PAGES_ON_MENU = True
TWITTER_USERNAME = 'twitter-user-name'
MENUITEMS = (('Blog', SITEURL),)
</pre></div>
<p>In my own setup, I also discovered a non-documented variable <code>PAGES = True</code> required to have static pages appearing in my Blog Menu (in addition to having a <code>pages</code> subdirectory in the <code>content</code> directory). But that may be related to the way the specific way the <code>pelican-blue</code> theme is developed.</p>
<p>Now, regenerate our blog with the new theme and check the result:</p>
<div class="highlight"><pre><span></span>$ pelican content
$ ./development_server.sh start
</pre></div>
<p>And open your browser at <a href="http://localhost:8000">http://localhost:8000</a>.</p>
<h3>Publish your local Blog copy to your GitHub repository</h3>
<p>During the 1st step, we've created the GitHub repository for the User page.</p>
<p>Since then, we've generated and tested some content locally.</p>
<p>So now, we want to upload our content, I mean the files in the <code>output</code> directory of your project to the <code>master</code> branch of your GitHub User page repository, which is the branch that will be accessible through the <code>https://<github-username>.github.io</code> URL.</p>
<p>For that, it's time to use the <code>ghp-import</code> tool installed earlier. This very practical tool will avoid use playing with branches and directories, and will care about this for us.</p>
<p>The pelican website documents the instructions to be used:</p>
<div class="highlight"><pre><span></span>$ pelican content -o output -s publishconf.py
$ ghp-import -b master -p output
</pre></div>
<p><strong>Note:</strong></p>
<ul>
<li>
<p>the 1st command generates the files in the output directory using the <code>publishconf.py</code> files, which has been generated by the <code>pelican-quickstart</code> tool and adds a few additional steps after the <code>pelicanconf.py</code> files to make our static site ready for publication on the net,</p>
</li>
<li>
<p>the 2nd command commits the files in the <code>output</code> directory to the <code>master</code> branch of the remote repo.</p>
</li>
</ul>
<p>I also added a few classical commands in order to push the whole pelican project repository to the <code>pelican</code> branch of the GitHub repo:</p>
<div class="highlight"><pre><span></span>$ git add .
$ git commit -m <span class="s2">"addons to my pelican blog"</span>
$ git push -u origin pelican
</pre></div>
<p>Now, navigate to <code>https://<github-username>.github.io/</code> and enjoy the result of your work!</p>
</div>
<div class="post_list">
<span>By </span>
<a href="https://rabierp.github.io/author/pascal-rabier.html">@Pascal Rabier</a>
<span> in </span>
<span class="post_category"><a href="https://rabierp.github.io/category/blogging.html" rel="bookmark" title="Permalink to Blogging">[ Blogging ]</a></span>
<span class="post_date">lun. 17 avril 2017</span>
<div><span>Tags : </span>
<span><a href="https://rabierp.github.io/tag/pelican.html">#pelican, </a></span>
<span><a href="https://rabierp.github.io/tag/markdown.html">#markdown, </a></span>
<span><a href="https://rabierp.github.io/tag/ghpages.html">#ghpages, </a></span>
</div>
<div class="entry-social">
<span class="twitter"><a target="_blank" rel="nofollow" onclick="javascript:window.open(this.href, '', 'menubar=no,toolbar=no,resizable=yes,scrollbars=yes,height=400,width=700');return false;" title="Twitter" href="https://twitter.com/share?url=https://rabierp.github.io/setting-up-a-github-blog-with-pelican.html&text=Setting up a GitHub blog with Pelican&via=@SWDefinedInfra"><img src="https://rabierp.github.io/theme/images/icons/twitter-s.png"></a></span>
<span class="gplus"><a target="_blank" title="Google +" href="https://plus.google.com/share?url=https://rabierp.github.io/setting-up-a-github-blog-with-pelican.html&hl=fr" rel="nofollow" onclick="javascript:window.open(this.href, '', 'menubar=no,toolbar=no,resizable=yes,scrollbars=yes,height=450,width=650');return false;"><img src="https://rabierp.github.io/theme/images/icons/google-s.png"></a></span>
<span class="facebook"><a target="_blank" title="Facebook" rel="nofollow" onclick="javascript:window.open(this.href, '', 'menubar=no,toolbar=no,resizable=yes,scrollbars=yes,height=500,width=700');return false;" href="https://www.facebook.com/sharer.php?u=https://rabierp.github.io/setting-up-a-github-blog-with-pelican.html&t=Setting up a GitHub blog with Pelican"><img src="https://rabierp.github.io/theme/images/icons/facebook-s.png"></a></span>
<a target="_blank" title="Linkedin" href="https://www.linkedin.com/shareArticle?mini=true&url=https://rabierp.github.io/setting-up-a-github-blog-with-pelican.html&title=Setting up a GitHub blog with Pelican" rel="nofollow" onclick="javascript:window.open(this.href, '', 'menubar=no,toolbar=no,resizable=yes,scrollbars=yes,height=450,width=650');return false;"><img src="https://rabierp.github.io/theme/images/icons/linkedin-s.png"></a>
<span class="mail"><a href="mailto:?subject=Setting up a GitHub blog with Pelican&body=Viens découvrir un article à propos de [Setting up a GitHub blog with Pelican] sur le site de Pascal Rabier. https://rabierp.github.io/setting-up-a-github-blog-with-pelican.html" title="Share by Email" target="_blank"><img src="https://rabierp.github.io/theme/images/icons/mail-s.png"></a></span>
</div>
</div>
</article>
</section>
</article>
<!-- Footer -->
<footer>
<p>
Blog powered by <a href="http://getpelican.com/">Pelican</a>,
which takes great advantage of <a href="http://python.org">Python</a>.
Theme <a href="https://github.com/parbhat/pelican-blue">Pelican-Blue</a> by <a href="https://parbhatpuri.com/">@parbhat</a>.
</p>
</footer>
</body>
</html>