Skip to content

Commit a917eab

Browse files
mattmakaimattmakai
committed
closing in on finishing new post and 100k words
1 parent f64e2e8 commit a917eab

File tree

6 files changed

+223
-25
lines changed

6 files changed

+223
-25
lines changed

‎content/posts/170605-static-sites-pelican.markdown‎

Lines changed: 223 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
title: How to Create Your First Static Website with Pelican and Jinja2
1+
title: How to Create Your First Static Site with Pelican and Jinja2
22
slug: generating-static-websites-pelican-jinja2-markdown
33
meta: Learn how to generate static websites with Python, the Pelican static site generator, Jinja2 and Markdown.
44
category: post
55
date: 2017-06-05
6-
modified: 2017-06-05
6+
modified: 2017-06-07
77
headerimage: /img/170605-static-sites-pelican/header.jpg
88
headeralt: Pelican, Jinja2 and Markdown logos.
99

@@ -20,8 +20,14 @@ with existing files rather than executing any code on the server during
2020
the HTTP request-response cycle.
2121

2222
In this tutorial you will learn how to create a
23-
[basic static website](/static-site-generator.html) that you can further
24-
customize and expand with your own design and content.
23+
[static website](/static-site-generator.html) from scratch
24+
using [Pelican](/pelican.html).
25+
26+
<img src="/img/170605-static-sites-pelican/gunship-bootstrap-css.png" width="100%" class="technical-diagram img-rounded" style="border:1px solid #ccc" alt="Articles page after Bootstrap CSS has been added.">
27+
28+
Our simple static site will have pages that look like the above screenshot
29+
but the entire site can be easily customized and expanded with your own design
30+
and content.
2531

2632

2733
## Our Tools
@@ -212,6 +218,9 @@ Use the `ps` and `grep` commands to view the process then stop the process
212218
with the `kill` command as follows. Remember that your process ID will almost
213219
definitely be different from the `1365` ID for my process.
214220

221+
Kill the development server now so that we can use different commands to
222+
serve our site after we create our initial content.
223+
215224
```
216225
(staticsite) $ ps -A | grep 1365
217226
1365 ttys003 0:01.43 /Library/Frameworks/Python.framework/Versions/3.6/Resources/Python.app/Contents/MacOS/Python /Users/matt/Envs/staticsite/bin/pelican --debug --autoreload -r /Users/matt/devel/py/retrosynth/content -o /Users/matt/devel/py/retrosynth/output -s /Users/matt/devel/py/retrosynth/pelicanconf.py
@@ -236,23 +245,49 @@ Pelican can accept both [Markdown](/markdown.html) and reStructureText
236245
markup files as input.
237246

238247
Create a new subdirectory under the `content` named `posts`. Change into
239-
the `posts` directory. Create a new file named `first_post.markdown` with
248+
the `posts` directory. Create a new file named `gunship.markdown` with
240249
the following content.
241250

242251
```markdown
243-
...
252+
title: Gunship
253+
slug: gunship
254+
category: bands
255+
date: 2017-06-05
256+
modified: 2017-06-06
257+
258+
259+
[Gunship](https://www.gunshipmusic.com/) is a *retro synthwave* artist out of the UK.
260+
261+
[Revel in Your Time](https://www.youtube.com/watch?v=uYRZV8dV10w),
262+
[Tech Noir](https://www.youtube.com/watch?v=-nC5TBv3sfU),
263+
[Fly for Your Life](https://www.youtube.com/watch?v=Jv1ZN8c4_Gs)
264+
and
265+
[The Mountain](https://www.youtube.com/watch?v=-HYRTJr8EyA)
266+
are all quality songs by Gunship. Check out those amazing music videos!
267+
268+
Also take a look at other retro synthwave artists such as
269+
[Trevor Something](https://trevorsomething.bandcamp.com/),
270+
[Droid Bishop](https://droidbishop.bandcamp.com/),
271+
[FM-84](https://fm84.bandcamp.com/)
272+
and
273+
[Daniel Deluxe](https://danieldeluxe.bandcamp.com/).
244274
```
245275

246-
What does our server look like now that we wrote our first post?
276+
What does our server look like now that we wrote our first post?
277+
247278

248-
We used the `make devserver` command earlier, but what other commands are
249-
available to us via the `Makefile`?
279+
Our `make` file can also help us regenerate the site when changes occur
280+
if we choose to not use the development server.
250281

282+
We used the `devserver` task earlier, but what other task are available
283+
to us via the `Makefile`?
251284

252285
```bash
253286
make
254287
```
255288

289+
`make` should show us all of the following tasks we can run.
290+
256291
```
257292
Makefile for a pelican Web site
258293
@@ -277,24 +312,33 @@ Set the DEBUG variable to 1 to enable debugging, e.g. make DEBUG=1 html
277312
Set the RELATIVE variable to 1 to enable relative urls
278313
```
279314

280-
```
281-
make html
315+
The `html` task is what we are looking for to invoke the `pelican` command
316+
using our `pelicanconf.py` settings file.
282317

318+
```
319+
(staticsite) $ make html
283320
pelican /Users/matt/devel/py/retrosynth/content -o /Users/matt/devel/py/retrosynth/output -s /Users/matt/devel/py/retrosynth/pelicanconf.py
284-
WARNING: No valid files found in content.
285-
Done: Processed 0 articles, 0 drafts, 0 pages and 0 hidden pages in 0.07 seconds.
321+
Done: Processed 1 article, 0 drafts, 0 pages and 0 hidden pages in 0.14 seconds.
286322
```
287323

288-
If you used the `make devserver` command earlier then give Python's built-in
289-
HTTP server a shot with the following command.
324+
Our site has been regenerated and placed in the `output` directory.
325+
326+
If you used the `make devserver` command earlier then change into the `output`
327+
directory and give Python's built-in HTTP server a shot with the following
328+
command.
290329

291330
```
331+
cd output
292332
python -m http.server
293333
```
294334

295-
You can change the port binding by adding a number after the command, if you
296-
want to serve more than one static site at a time or you already have an
297-
application bound to port 8000.
335+
Our first post in all its glory...
336+
337+
<img src="/img/170605-static-sites-pelican/gunship-first-post.png" width="100%" class="technical-diagram img-rounded" style="border:1px solid #ccc" alt="Gunship as our first band post on retro synthwave static site.">
338+
339+
You can change the HTTP server port binding by adding a number after the
340+
command, if you want to serve more than one static site at a time or you
341+
already have an application bound to port 8000.
298342

299343
```
300344
python -m http.server 8005
@@ -303,30 +347,184 @@ python -m http.server 8005
303347
Note that if you are using Python 2 the equivalent HTTP server command is
304348
`python -m SimpleHTTPServer`.
305349

350+
We now have some very basic site content. We could expand this start into many
351+
more posts and pages but let's learn how to modify the site configuration.
306352

307353

308-
## Edit the Configuration
309-
Pelican's quickstart assumes a bunch of defaults that may or may not be
354+
## Edit Site Configuration
355+
Pelican's quickstart assumed a bunch of defaults that may or may not be
310356
applicable to your site. Open up the `pelicanconf.py` file to change some
311357
of the defaults.
312358

313359
Look for the `TIMEZONE` variable. If it's not right for your location
314360
then modify it to your zone. Wikipedia has a handy
315361
[table of valid time zones values](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
316362

363+
Also modify the `LINKS` tuple to include your site (or Full Stack Python!)
364+
instead of including the "you can modify those links" link. Change the
365+
last line of `LINKS` so it looks like the following tuple of tuples.
366+
367+
```python
368+
# Blogroll
369+
LINKS = (('Pelican', 'http://getpelican.com/'),
370+
('Python.org', 'http://python.org/'),
371+
('Jinja2', 'http://jinja.pocoo.org/'),
372+
('Full Stack Python', 'https://www.fullstackpython.com/'),)
373+
```
374+
375+
Instead of using the `make html` file, this time we will invoke the
376+
`pelican` command directly from the command line. There is nothing wrong
377+
with the `Makefile`, but it is a good idea to get comfortable with Pelican
378+
directly instead of only through build files.
379+
380+
```bash
381+
pelican -s pelicanconf.py -o output content
382+
```
383+
384+
Now run the HTTP server if you do not already have it running in another
385+
terminal window.
386+
387+
```
388+
cd output
389+
python -m http.server
390+
```
391+
392+
Head back to the browser and refresh to view the updated configuration.
393+
394+
<img src="/img/170605-static-sites-pelican/updated-configuration.png" width="100%" class="technical-diagram img-rounded" style="border:1px solid #ccc" alt="New links created by the pelicanconf.py configuration settings file.">
395+
396+
What happens when we click on the blog post title? It takes us to a
397+
very similar-looking page with the
398+
[localhost:8000/gunship.html](http://localhost:8000/gunship.html) URL.
399+
400+
<img src="/img/170605-static-sites-pelican/gunship-post.png" width="100%" class="technical-diagram img-rounded" style="border:1px solid #ccc" alt="Gunship subpage for the site.">
401+
402+
Alright, we updated some basic site-wide data, but our site really could
403+
use a change of paint.
404+
405+
406+
## Modify Site Theme
407+
Changing the site theme is really where you can turn a standard blog into
408+
whatever type of site you want to build. While the default Pelican
409+
configuration creates a blog template, you do not need to have a
410+
chronological structure if it is not right for your website.
411+
412+
Create a new directory under your project directory that is named
413+
`theme`. Within `theme` create another directory named `templates`.
414+
`templates` is where our [Jinja2](/jinja2.html) templates will be stored and
415+
can override the default theme.
416+
417+
...base.html...
418+
419+
```jinja2
420+
```
421+
422+
Within `theme/templates` create a file named `article.html` that will have a
423+
different theme for blog posts than the rest of the site. Fill `article.html`
424+
with the following Jinja2 markup.
425+
426+
```jinja2
427+
<!DOCTYPE html>
428+
<html lang="en">
429+
<head>
430+
<title>{{ article.title }}</title>
431+
</head>
432+
<body>
433+
<div class="container">
434+
<div class="row">
435+
<div class="col-md-8">
436+
<h1>{{ article.title }}</h1>
437+
<label>Posted on <strong>{{ article.date }}</strong></label>
438+
{{ article.content }}
439+
</div>
440+
</div>
441+
</div>
442+
</body>
443+
</html>
444+
```
445+
446+
Next we will use a Jinja2 template to override the default `index.html` main
447+
page. Again within the `theme/templates` directory, create a file named
448+
`index.html` with the following markup.
449+
450+
```jinja2
451+
<!DOCTYPE html>
452+
<html lang="en">
453+
<head>
454+
<title>{{ SITENAME }}</title>
455+
<!-- Latest compiled and minified Bootstrap CSS -->
456+
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
457+
</head>
458+
<body>
459+
<div class="container">
460+
<div class="row">
461+
<div class="col-md-8">
462+
<h1>{{ SITENAME }}</1>
463+
{% for article in articles %}
464+
<h2><a href="/{{ article.slug }}.html">{{ article.title }}</a></h2>
465+
<label>Posted on <strong>{{ article.date }}</strong></label>
466+
{{ article.content|truncate(110) }}
467+
{% else %}
468+
No posts yet!
469+
{% endfor %}
470+
</div>
471+
</div>
472+
</div>
473+
</body>
474+
</html>
475+
```
476+
477+
Regenerate the site and make sure you are serving it with the development
478+
server or the `python -m http.server` command.
479+
480+
Make sure to use the new `-t theme` flag to specify that the Jinja2
481+
templates within the `theme` directory should be applied to the site.
482+
483+
```bash
484+
pelican -s pelicanconf.py -o output -t theme content
485+
```
486+
487+
Go to [localhost:8000](http://localhost:8000) and refresh the page.
488+
The styling on the main page remains the same because it is not a
489+
blog post, but a page with a collection of the blog articles.
490+
491+
<img src="/img/170605-static-sites-pelican/basic-theme.png" width="100%" class="technical-diagram img-rounded" style="border:1px solid #ccc" alt="Basic theme remains unchanged.">
492+
493+
Click on the Gunship post however and we see that the `article.html`
494+
"styling" has been applied to the page.
495+
496+
<img src="/img/170605-static-sites-pelican/gunship-no-styling.png" width="100%" class="technical-diagram img-rounded" style="border:1px solid #ccc" alt="Articles have an entirely different theme based on article.html markup.">
497+
498+
Pretty sparse! We can at least add the Bootstrap CSS to the HTML to
499+
align our content.
500+
501+
Within `article.html`, add the following line for Bootstrap under
502+
`<title>{{ article.title }}</title>`.
503+
504+
```jinja2
505+
<!-- Latest compiled and minified Bootstrap CSS -->
506+
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous">
507+
```
508+
509+
Regenerate the site and refresh the Gunship page.
510+
511+
<img src="/img/170605-static-sites-pelican/gunship-bootstrap-css.png" width="100%" class="technical-diagram img-rounded" style="border:1px solid #ccc" alt="Articles page after Bootstrap CSS has been added.">
317512

318-
## Modify the Site Theme
513+
Well at least our design has moved from 1996 to 2001. I am sure you can
514+
do a whole lot more to improve your own site's design.
319515

516+
The new `article.html` is not much of a theme for now but it at least
517+
provides a fresh start for completely customized blog posts.
320518

321519

322520
## What's next?
323521
You generated your first [Pelican](/pelican.html) static website using
324-
[Markdown](/markdown.html) and [Jinja2](/jinja2.html). You can
325-
now make additional modifications to the Jinja2 templates, build new pages
326-
and add more content via Markdown files.
522+
[Markdown](/markdown.html) and [Jinja2](/jinja2.html). Additional modifications
523+
can be made to the Jinja2 templates and the content contained in the Markdown
524+
files.
327525

328526
Do you want to deploy your new static website to GitHub Pages or an S3 bucket?
329-
Well, that's a story for another Full Stack Python tutorial...
527+
Well, that's a story for another [Full Stack Python tutorial](/blog.html)...
330528

331529
Questions? Let me know via
332530
[a GitHub issue ticket on the Full Stack Python repository](https://github.com/mattmakai/fullstackpython.com/issues),

‎static/img/170605-static-sites-pelican/gunship-bootstrap-css.png‎

132 KB
Loading

‎static/img/170605-static-sites-pelican/gunship-first-post.png‎

238 KB
Loading

‎static/img/170605-static-sites-pelican/gunship-no-styling.png‎

137 KB
Loading

‎static/img/170605-static-sites-pelican/gunship-post.png‎

276 KB
Loading

‎static/img/170605-static-sites-pelican/updated-configuration.png‎

362 KB
Loading

0 commit comments

Comments
 (0)