--- title: Blog initialisation date: 2021-10-05 slug: init authors: - lunik description: I'm explaining how I have created this blog tags: - blog - website - pelican - python - it - sysops --- ![cover](/blog/img/posts/2021-10-05-init/cover.png) First of all I'm not a web engineer and I hate web development. There are too many framework to work with ([ReactJS][reactjs-website], [Angular][angular-website], [jquery][jquery-website], ...). [Javascript][javascript-website] asynchronous system is a pain to manage at large scale. And dependencies maintainability is too much for me (yes, I'm talking about you `npm`). I'm not a web designer either so [HTML][html-rfc]/[CSS][css-rfc] are the enemy (mostly because I don't know how to use them at their full potentials). This is pretty much why I quit web development in the first place and became a SysOps engineer. :::danger This blog post is deprecated. I left it online for historical reasons. Now the blog is generated with [MKDocs][mkdocs-website]. ::: ### Theory first This is a static website. No fancy [Javascript][javascript-website], framework or other [CMS][cms-wikipedia]. All pages and medias are served through a very simple web hosting setup that I will detail in another blog post later. ### How is it generated then ? I did not want to over-think too much on the website structure ([HTML][html-rfc] & company) and I wanted to focus on the content of the blog. So I searched for a tool to generate a fancy website from simple text files. #### Digression A lot of people already know about [Jekyll][jekyll-website]. It's a [Ruby][ruby-website] based tool that do the job just fine. Setup some config files, write your article as plain text file, build and ... here you go a fancy website. But wait ! I didn't use [Jekyll][jekyll-website] because IMHO it's overkill for my needs. Why you may ask ? Well : - I'm didn't know anything about [Ruby][ruby-website] so it's pretty hard to debug anything - [Ruby][ruby-website] package dependencies are a pain in the ass - [Jekyll][jekyll-website] plugin are (for most the majority) community driven so a lot of them are incompatible with each other, have missing documentation or simply doesn't work - I have already deployed another blog a few years ago with [Jekyll][jekyll-website] and I don't have goo memories. I still maintain it but it's not my cup of tee ... #### So the solution then ? I use [Pelican][pelican-website] ! ![logo Pelican](/blog/img/posts/2021-10-05-init/getpelican.jpg) It's a simple static site generator tool that require only [Python][python-website] to run. It allow me to write my blog post as plain text [Markdown][markdown-rfc]. [HTML][html-rfc] files are templated using [Jinja][jinja-website]. Being a SysOps engineer, [Python][python-website], [Markdown][markdown-rfc], [Jinja][jinja-website] are, among other, some keyword that put a smile on my face ! (It even come with a [Makefile][make-website] !!) So [Pelican][pelican-website] is a tools that generate static [HTML][html-rfc] website from [Markdown][markdown-rfc] files and [Jinja][jinja-website] templates. Great ?! When do we begin ?! ### Practice I'm not going to reinvent the wheel, so follow the great [Pelican Quick Start guide][pelican-quick-start] and then come back for more deep dive into my setup for this blog website. #### Requirement I have [Python][python-website] 3.9.6 installed on my PC and I'm running inside a [VirtualEnv][python3-venv]. Create the [VirtualEnv][python3-venv] : ``` python3 -m venv venv ``` Get inside : ``` source venv/bin/activate ``` Install the required packages : ``` pip install "pelican[markdown]" ``` #### File organization This is my current folders/files layout (FYI this is the default one provided by [Pelican settings][pelican-settings]): ```shell . ├── Makefile ├── content │ ├── articles │ │ ├── init-en.md │ │ └── init-fr.md │ ├── images │ │ └── logo.png │ └── pages ├── output ├── pelicanconf.py ├── publishconf.py ├── tasks.py └── theme └── flex ``` - The `content` folder contains all the articles, pages and medias sorted in three folders : - `articles` for blog posts - `images` for media contents - `pages` for additional static pages on the blog - The `output` folder will contains all the generated [HTML][html-rfc] and [CSS][css-rfc] static files after building the website. - The `theme` folder contains the current website theme. I'm currently using the [Flex][pelican-flex-theme] theme from the community. - The files `Makefile` and `tasks.py` is auto generated by [Pelican][pelican-website] when creating the project with [Pelican quick start guide][pelican-quick-start] - The file `pelicanconf.py` contains default [Pelican settings][pelican-settings]. - And then `publishconf.py` contains [Pelican specific configuration][pelican-settings] to apply when publishing the blog. #### Configuring the blog I use the default configuration provided during the [Pelican quick start guide][pelican-quick-start] and just added two are three additional configuration. #### Building the blog Now that I have a full website, I need to build it. When I'm developing the blog (or when writing articles), I'm using the following commande : ```shell make devserver ``` It build all the blog pages and serve it with à small local webserver accessible at [http://localhost:8000](http://localhost:8000). When I'm happy with the look of the blog/articles, I use the provided commande to build a publishable version of the website : ```shell make publish ``` All the website files are now generated in the `output` folder : ```shell output ├── 404.html ├── archives.html ├── authors.html ├── categories.html ├── drafts │ ├── init-fr.html │ └── init.html ├── images │ ├── getpelican.jpg │ ├── getpelican.png │ └── logo.png ├── index.html ├── tags.html └── theme └── ... ``` The main difference between those commandes is that `publish` use the `publishconf.py` config and `devserver` use only `pelicanconf.py` ### Conclusion Now I have a fully built blog environment and I only need to write new articles, `make publish` and *voila*. I a futur blog post, I will explain how I'm hosting those static file to make them accessible on internet. [angular-website]: https://angular.io [cms-wikipedia]: https://en.wikipedia.org/wiki/Content_management_system [css-rfc]: https://tools.ietf.org/html/rfc7993 [html-rfc]: https://tools.ietf.org/html/rfc1866 [javascript-website]: https://developer.mozilla.org/en-US/docs/Web/JavaScript [jekyll-website]: https://jekyllrb.com [jinja-website]: https://jinja.palletsprojects.com [jquery-website]: https://jquery.com [make-website]: https://www.gnu.org/software/make [markdown-rfc]: https://tools.ietf.org/html/rfc7763 [pelican-flex-theme]: https://github.com/alexandrevicenzi/Flex [pelican-quick-start]: https://docs.getpelican.com/en/latest/quickstart.html [pelican-settings]: https://docs.getpelican.com/en/latest/settings.html [pelican-website]: https://getpelican.com [python-website]: https://www.python.org [python3-venv]: https://docs.python.org/fr/3/library/venv.html [reactjs-website]: https://reactjs.org [ruby-website]: https://www.ruby-lang.org [mkdocs-website]: https://www.mkdocs.org