As a start why not actually have a look at this website? As you've seen it just consists of a bunch of HTML files. Of course I did not write each and every one by hand. Instead I'm using a Static Site Generator.
That means, I write the content reStructuredText and a program generates the HTML files.
So it's almost like WordPress. The only difference is that I don't have any active code on the webserver, which means that the server has a smaller attack surface.
There are way too many static site generators in the world to choose from, so I made my selection by what markup languages are supported and what language the generator itself was written it. So it boiled down to Pelican 1.
The quickstart, as provided by the good people over at Pelican, is a reasonably good start. Once you ran
pelican-quickstart (don't worry about all those questions too much, you can change the values later again) you will get a directory structure like this:
content is where you put, well, the content. And the script will generate all the HTML files in
There are two script files, as you can see:
publishconf.py. The former is used during development, i.e. while you're in the process of writing you websites, and the latter is used when you generate the website for publishing.
publishconf.py should contain this line somewhere at the top:
Which means that all configurations in
pelicanconf.py also apply in
publishconf.py but additional settings in the latter file are also used during the generation.
How to work with it
What I usually do is, I run a webserver in the output directory:
And open http://127.0.0.1:8000 in my browser. Now the work on the website proceeds in this way:
Edit the content files,
Run the generator (
pelican -s pelicanconf.py),
Refresh the website,
Repeat until happiness sets in.
By default pelican expects you to create content in specific directories, which means you have to create the folders first:
├── content │ ├── articles │ ├── images │ └── pages ├── output ├── pelicanconf.py └── publishconf.py
I guess it's obvious what goes into the
images folder. But what's the difference between articles and pages?
In pelican articles are the main content of your page: blog posts, galleries, limericks, or whatever floats your boat.
pages are everything else like mission statements, contact page, About the author and such.
Both pages and articles can be written in Markdown, reStructuredText, or HTML. I prefer reStructuredText, so an article could look like this:
############# Article Title ############# :date: 2019-01-21 14:23 :author: Darel B. Tudar :tags: example Here comes the text!
Only date and title are required. The author is taken from the configuration file and everything else is left emtpy if you don't specify it.
To select the theme you could clone one of the available themes and put the reference to it into your
And then inside your
It's fairly easy to write your own theme by looking at the basic theme and reading up on it in the documentation.
There are many plugins over at https://github.com/getpelican/pelican-plugins to enhance the generation of your site, like galleries, thumbnails, comments, or analytics (by using 3rd parties like disqus or google analytics, if that's something you'd like to do to your visitors).
I use git for versioning both the theme and the website. However, I keep the theme in a separate repository, because it seems like bad style to mix the content and the theme in the same repository.
. ├── website │ ├── .git │ ├── .gitignore │ ├── content │ ├── output │ ├── pelicanconf.py │ └── publishconf.py └── theme ├── .git ├── static └── templates
.gitignore looks pretty much like this:
But I don't put big pictures on my website, so my repository doesn't blow up.
Some final words
Pelican can do much more than what you see here (from translations to RSS/Atom feeds). One of the nice, but for beginners overwhelming, parts is that you can configure almost everything. Don't want to call the folder for your articles articles? You can configure that. Want to have your images in a directory outside the normal file structure? You can configure that.
Once you get comfy with how it works and have set up your first playground website, revisit the documentation to find all the nice features and gems that Pelican offers.