DEV Community: Mathieu

Wisewand : L'outil de rédaction IA français pour optimiser votre SEO

Mathieu — Fri, 28 Feb 2025 14:18:54 +0000

Profitez de 10% de réduction avec le code promo : MINUTE10

Vous recherchez un outil de rédaction IA performant et rapide pour améliorer votre stratégie SEO ? Wisewand pourrait répondre à vos attentes. Développé par une équipe d'experts SEO (Antho, Arthur et Franck de Les Wizards), cet outil se distingue par sa facilité d'utilisation et son efficacité.

Surpassant les solutions de rédaction IA traditionnelles, ce logiciel 100% français propose de nombreuses fonctionnalités visant à créer du contenu fluide, optimisé et conforme aux exigences des moteurs de recherche.

Wisewand offre plusieurs formules adaptées à tous les budgets avec un excellent rapport qualité/prix. Vous pouvez également bénéficier d'une réduction de 10% avec le code promo MINUTE10, parfait pour commencer à moindre coût.

Points forts et limites

Decouvrez notre test complet sur https://nugg.ad/fr/avis-wisewand/

Avantages

Interface intuitive et simple d'utilisation
Contenu IA de haute qualité
Optimisation SEO et maillage interne automatisés
Intégration directe avec WordPress et Shopify
Plusieurs modes de rédaction adaptés à différents besoins

Inconvénients

Absence de version gratuite

Fonctionnalités principales

Wisewand se démarque par ses fonctionnalités complètes, conçues pour simplifier la création de contenu optimisé pour le référencement, quel que soit votre profil : éditeur de site, blogueur, e-commerçant ou agence digitale.

Création de personas

Wisewand permet de définir des personas en analysant le contexte et les besoins de votre audience cible. En renseignant quelques informations essentielles (âge, sexe, centres d'intérêt, comportement d'achat), l'outil adapte automatiquement le ton et le style rédactionnel, favorisant ainsi une meilleure conversion et un engagement accru des lecteurs.

Mode de rédaction autopilot

Cette fonctionnalité gère automatiquement la structure et l'optimisation SEO du contenu. Il suffit d'entrer un mot-clé principal pour générer un article optimisé en quelques minutes. Chaque texte répond précisément à l'intention de recherche des internautes et intègre naturellement des liens internes et des mots-clés secondaires pertinents.

Mode de rédaction avancé

Destiné aux rédacteurs expérimentés, ce mode offre un contrôle plus précis sur le contenu :

Personnalisation de la longueur et de la structure des articles
Définition précise des balises Hn (H1, H2, H3)
Choix d'un ton spécifique adapté à l'intention de recherche
Affinage de la mise en forme (listes, tableaux, citations)

Mode de rédaction affiliation

Spécialement conçu pour les affiliés, ce mode se concentre sur l'intention commerciale et l'optimisation des conversions. Il intègre naturellement des éléments promotionnels et des appels à l'action adaptés aux intentions d'achat, idéal pour augmenter vos commissions.

Flux RSS

Pour les sites d'actualités ou de niches spécifiques, Wisewand permet d'intégrer des flux RSS externes. Cette fonctionnalité s'appuie sur des sources d'information fiables pour créer régulièrement des articles optimisés, éliminant ainsi le besoin de mise à jour manuelle.

Tarifs

Wisewand propose quatre formules basées sur un système de crédits (2 crédits = 1 article) :

Explorer : 47€ (environ 23 articles)
Creator : 197€ (environ 100 articles)
Master : 497€ (environ 300 articles)
Titan : 997€ (environ 650 articles)

Selon la formule choisie, vous pouvez bénéficier de réductions allant de 5% à 33%. Toutes les fonctionnalités avancées sont incluses dans chaque offre.

Pourquoi choisir Wisewand ?

Humanisation du contenu

Contrairement à d'autres outils qui produisent des textes impersonnels, Wisewand génère des articles naturels et engageants. L'algorithme intègre des nuances subtiles pour créer une rédaction fluide et parfaitement adaptée à l'expérience de lecture humaine.

Prix compétitifs

Comparé à ses concurrents, Wisewand propose des fonctionnalités avancées à un prix accessible. Son système de crédits offre une grande flexibilité d'utilisation, s'adaptant aussi bien aux particuliers qu'aux grandes agences.

Gestion automatisée du maillage interne

Wisewand insère automatiquement des liens internes pertinents dans chaque article, améliorant ainsi l'indexation et le référencement naturel du site. Cette fonctionnalité permet de gagner du temps tout en optimisant la cohérence entre les différentes pages.

Accessibilité pour tous les créateurs de contenu

Que vous soyez débutant ou expert, Wisewand s'adapte à tous les profils. L'outil ne nécessite aucune compétence en prompt engineering et son interface intuitive permet une prise en main rapide.

Alternatives à Wisewand

Bien que Wisewand offre de nombreux avantages, d'autres outils existent sur le marché :

Skoatch : propose une rédaction automatisée abordable mais moins spécialisée en SEO
TextBulker : idéal pour la production en grande quantité, mais parfois moins fluide
ChatGPT : très polyvalent mais nécessite des ajustements manuels pour l'optimisation SEO

Wisewand se démarque par sa spécialisation SEO et son approche intégrée, offrant une solution complète pour les créateurs de contenu qui cherchent à allier qualité et simplicité d'utilisation.

Structuring a Python application

Mathieu — Sat, 26 Sep 2020 09:38:23 +0000

Original article : https://brainsorting.dev/posts/structuring-a-python-application/

In this short article I will explain all the different ways of structuring a Python application, from a quick script to a more complex web application.

Single python file containing all the code

That's okay for code without dependencies or using a virtual environment. This is generally used for a quick script that doesn't need complexity in its file structure.

my-single-file-project/
├── .gitignore
├── helloworld.py
├── test.py
├── pyproject.toml
├── LICENSE
└── README.md

Example of the helloworld.py :

#!/usr/bin/env python
# helloworld.py

from datetime import datetime

def do_hello():
    print(f"Hello, today is {datetime.now().date()}")

if __name__ == '__main__':
    do_hello()

Installable Single Package

When your app get more complex you generally wants to group your different files and helpers into a module.

You also need to improve your tests so they cover all the files → test coverage. You can also add the use of a linter.

my-single-package-app/
├── helloworld/
│   ├── __init__.py
│   ├── helloworld.py
│   └── utils.py
├── tests/
│   ├── __init__.py
│   ├── test_helloworld.py
│   └── test_utils.py
├── runtest.sh
├── .gitignore
├── pyproject.toml
├── LICENSE
└── README.md

Now we grouped the files from our app in two folders, the helloworld app folder and the tests folder.

We match the test_****.py files name with the files in the app module folder.

The __init__.py files are mandatory for python to know it is package and can be empty.

#!/usr/bin/env python
# helloworld.py

from datetime import datetime

from helloworld.utils import show_message

def do_hello():
    show_message(f"Hello, today is {datetime.now().date()}")

if __name__ == '__main__':
    do_hello() # pragma: no cover

runtests.sh file is a script to run all the test with the coverage dependency that you can install with poetry add coverage -D :

#!/bin/bash

find . -name "*.pyc" -exec rm {} \;
coverage run -p --source=tests,helloworld -m unittest # this is where you add the
                                                      # folders you want to test
if [ "$?" = "0" ]; then
    coverage combine
    echo -e "\n\n================================================"
    echo "Test Coverage"
    coverage report
    echo -e "\nrun \"coverage html\" for full report"
    echo -e "\n"

    # pyflakes or its like should go here
fi

Application with internal packages

In bigger apps you will probably have multiple modules, particularly if you do a GUI.

Possible additions to your application are :

bin directory, wrapper for your entry point.
data directory, always separate your data from your code

app/
├── helloworld/
│   ├── __init__.py
│   ├── hello/
│   │   ├── __init__.py
│   │   ├── hello.py
│   │   └── utils.py
│   ├── world/
│   │   ├── __init__.py
│   │   └── world.py
├── tests/
│   ├── __init__.py
│   ├── hello/
│   │   ├── __init__.py
│   │   ├── test_hello.py
│   │   └── test_utils.py
│   ├── world/
│   │   ├── __init__.py
│   │   └── test_world.py
├── bin/
│   └── helloworld*
├── data/
│   └── translate.csv
├── docs/
│   ├── conf.py
│   ├── index.rst
│   ├── hello.rst
│   ├── world.rst
│   └── Makefile
├── runtest.sh
├── .gitignore
├── pyproject.toml
├── LICENSE
└── README.md

bin/

This new folder holds any executable files the users will use. The script drop the .py ending. It should have very little code logic, it's just a wrapper for the main module's entry point.

You can configure setup.py to package this if you build a wheel, the script will be put on the path.

data/

If there are files that are not code that is usually where they should end up. It is also useful for test data.

docs/

The documentation is very important if you want to share your app with users.

A very useful library for that is sphinx, it uses pydoc comments to build the doc automatically.

poetry add sphinx -D
poetry add sphinx-rtd-theme -D
cd docs
sphinx-quickstarts
make html

The .rst files are generated by sphinx-quickstart.

Django web application

After you've installed Django you can use this included command to generate the architecture of the project as Django expects it :

django-admin startproject django_world
django-admin startapp hello

You will end up with this basic folder tree where just a few things has been manually added :

django_world/
├── docs/
├── static/
│   └── style.css
├── templates/
│   └── base.html
├── resetdb.sh
├── runserver.sh
├── hello/
│   ├── __init__.py
│   ├── admin.py
│   ├── apps.py
│   ├── migrations/
│   │   └── __init__.py
│   ├── models.py
│   ├── tests.py
│   └── views.py
├── django_world/
│   ├── asgi.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
└── manage.py

The hello/ folder is where all the logic, model, views and so on live.

The static folder contains all the static contents (css, js,...).

The templates folder has all the html templates.

runserver.sh is a script that has only one line :

python manage.py runserver

resetdb.sh is a script for wiping all the database and start from scratch, it is just a helper tool :

#!/bin/bash

find . -name "*.pyc" -exec rm {} \;
rm db.sqlite3

python manage.py migrate

# python manage.py create_test_data
# comment that last line to use premade test data

Flask

Flask is proud to show a working web app with 10 lines of code, but in practice you'll never do that. Here is a complete folder organization :

flaskr/
│
├── flaskr/
│   ├── ___init__.py
│   ├── db.py
│   ├── schema.sql
│   ├── auth.py
│   ├── blog.py
│   ├── templates/
│   │   ├── base.html
│   │   ├── auth/
│   │   │   ├── login.html
│   │   │   └── register.html
│   │   │
│   │   └── blog/
│   │       ├── create.html
│   │       ├── index.html
│   │       └── update.html
│   │
│   └── static/
│       └── style.css
│
├── tests/
│   ├── conftest.py
│   ├── data.sql
│   ├── test_factory.py
│   ├── test_db.py
│   ├── test_auth.py
│   └── test_blog.py
│
├── .gitignore
└── MANIFEST.in

We can see that flask really uses python package way of working.

Source : https://realpython.com/python-application-layouts/

Create a proxy with a Raspberry Pi 3 (or above)

Mathieu — Thu, 27 Aug 2020 09:34:13 +0000

Original article : https://brainsorting.dev/posts/create-a-proxy-with-a-raspberry-pi-3-or-above/

If you need to use a proxy that has the same IP address as your home, here is a tutorial on how to do it.

Install and configure your Raspberry Pi OS

Install and configure a raspberry pi without a mouse nor a keyboard :

Download the last version of raspbian lite here and download Etcher which we will use to flash the disk image on the SD card.
Start Elena, select the Raspbian Lite imake disk, select the target which is the SD card you use for your raspberry pi and click on Flash!.

While the image disk is getting installed, we will create the file that contains the wifi information so the raspberry can connect to it automatically. Open a text note and paste this inside :

ctrl_interface=/run/wpa_supplicant
update_config=1
country=FR

network={
    ssid="internet_box_name"
    scan_ssid=1
    psk="password"
}

Replace internet_box_name and password by your home internet box settings and save that file underwpa_supplicant.conf

Then we will create an empty file which name is simply ssh. This file will tell the raspberry that you want to enable the SSH connection which is usually set off by default. With that settings on we will be able to connect to the raspberry pi through the network using another computer.

Place both files that you just created in the BOOT folder of the SD card you just flashed.

Congratulation ! Now you can eject the SD card and insert it in your raspberry pi.

If everything worked out, when you switch on your Raspberry Pi you should see it in the list of the device connected to your home internet network by checking your router.

Now the next step is to connect to your Raspberry Pi with SSH. Launch a terminal and if you are on mac type this command :

ssh pi@local_ip_of_your_raspberry

It will ask for a password, type raspberry

To avoid that IP to change, we will set a static IP to your raspberry. You need to modify the file dhcpd.conf located in the folder /etc/.

Once you have opened the file, go to the last line and add this content

interface eth0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1

interface wlan0
static ip_address=192.168.1.100/24
static routers=192.168.1.1
static domain_name_servers=192.168.1.1

Here, the eth0 correspond to a internet cable connection, and wlan0 to a internet wifi connection. Up to you to choose which one you will use.

Static ip_address indicate the IP that your Raspberry Pi will have when it switch on. usually the IP is of the type 192.168.1.x, replace the x by an available slot on your network. If your box is on a different IP address then modify static router et static domain_name_servers accordingly.

Save the file and exit.

Setting up the raspberry pi

1) Update the raspberry pi

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

2) Install terminal editor Joe

sudo apt-get install joe

3) Install the following

sudo apt-get -y install fail2ban software-properties-common
sudo apt-get install build-essential libevent-dev libssl-dev
cd /etc
sudo wget https://github.com/z3APA3A/3proxy/archive/0.8.12.tar.gz
sudo tar zxvf 0.8.12.tar.gz
sudo mv 3proxy-0.8.12 3proxy
cd 3proxy

4) Edit the file proxy.h

sudo joe src/proxy.h

And add the line following line above the other lines starting with #DEFINE

#define ANONYMOUS 1

5) Compile and install the software

sudo make -f Makefile.Linux
sudo make -f Makefile.Linux install

6) Download 3proxy.cfg

sudo wget https://gettraffic.pro/docs/3proxy.cfg

7) Edit the 3proxy.cfg with Joe

sudo joe 3proxy.cfg

8) Change those lines

users root:CL:passwd
...
allow root

To any username you prefer instead of root and change the passwd to a strong password. If you changed root to a different username don't forget to change allow root to allow and whatever username you decided. Save that file when you are finished

9) Change file permission

sudo chmod 700 3proxy.cfg

10) Download the script file

cd /etc/3proxy/scripts/rc.d/
sudo mv proxy.sh saved-proxy.sh
sudo wget https://gettraffic.pro/docs/proxy.sh

11) Start the proxy server

sudo sh /etc/3proxy/scripts/rc.d/proxy.sh start

It should give the output “Starting 3Proxy”. If it doesn’t then there is a problem somewhere in your config files.

12) Add it to the autorun so after reboot it will start again

sudo joe /etc/rc.local

And add line :

sh /etc/3proxy/scripts/rc.d/proxy.sh start

This line has to be added above the line exit 0.

The best way to check if everything is alright is by doing a full reboot of your Raspberry and checking if everything still works after the reboot :

sudo shutdown -r now

Access your Raspberry Pi with SSH outside your home local network

You will need to add the fixed IP you choose for your Raspberry Pi in your internet box router settings. Add this IP address in the DHCP settings (the aim of this tutorial is not to each how to do that so look ressources on google).

Now edit your NAT/PAT settings to redirect the port 22 (SSH) and 3129 (your proxy) to the fixed IP address you just set up in the DHCP.

Now to access your home internet network from outside, you need a way to now its public IP address which might change over time. We will use a very good services to achieve that is called no-ip.

Register on https://www.noip.com/
Create a hostname like « myraspberrypiproxy.ddns.net »

Install the DUC on your raspberry pi which will automatically update the public IP no-ip will redirect the hostname to :

cd /usr/local/src/
sudo wget http://www.no-ip.com/client/linux/noip-duc-linux.tar.gz
sudo tar xf noip-duc-linux.tar.gz
cd noip-2.1.9-1
sudo make install

Then a little bit of configuration

sudo cp /usr/local/src/noip-2.1.9-1/debian.noip2.sh /etc/init.d/noip2.sh
sudo joe /etc/init.d/noip2.sh

And add the following code abose this line DAEMON=/usr/local/bin/noip2:

#!/bin/sh
#
### BEGIN INIT INFO
# Provides:          noip2.sh
# Required-Start:    $remote_fs $local_fs
# Required-Stop:     $remote_fs $local_fs
# Should-Start:
# Should-Stop:
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Dynamic IP client updater
# Description:
### END INIT INFO

Now the client can be started, stopped or restarted manually

sudo /etc/init.d/noip2.sh <start|stop|restart>

Change files read write properties :

sudo chown root.root /etc/init.d/noip2.sh
sudo chmod +x /etc/init.d/noip2.sh

Start the server
```
sudo /etc/init.d/noip2.sh start
```
To allow starting the service automatically at startup, run the following command:
```
sudo update-rc.d noip2.sh defaults
```
Then try sudo reboot to see if service start by itself

To check if there is a running instance use this command :
```
sudo noip2 -S
```

Finish ! Now you should be able to connect to your proxy with the hostname address you used in no-ip and the port 3129 like this 'myraspberrypiproxy.ddns.net:3129'. The authorized username and password to connect to the proxy are the one you decided previously in the step 8 of configuring the proxy.

Useful Commands

If you need to reconfigure the DUC file from no-ip use that command : sudo /usr/local/bin/noip2 -C
Connect to the raspberry pi by SSH with Terminal (Mac) : ssh pi@ip Then yes, and type password
Check if there is a no-ip instance running sudo noip2 -S
Check if proxy is running ps -A

How to cancel a pending ethereum transaction with MetaMask

Mathieu — Sat, 15 Aug 2020 10:31:20 +0000

Original article : https://brainsorting.dev/posts/how-to-cancel-a-pending-ethereum-transaction-with-metamask/

Having a pending transaction can be quite annoying and usually happens when the network is heavy loaded and the fees are sky rocketing. Your transaction may have a too low gas fee and miner are just ignoring it to prefer others transaction with higher fees.

This result in you being stuck because until that transaction is resolved you cannot send any other transaction. Annoying right ?

Let's dive right in on how to fix this !

Gather all the informations we need

Prerequisite

This tutorial is about using MetaMask to cancel the pending transactions so you need to have it.

If you don't have MetaMask installed on chrome, here is the official address to do so.

Etherscan

The first step is to go on etherscan and paste the tx hash of your pending transaction. You can also paste your ethereum address and will be able to find all your pending transactions.

Find the oldest pending transaction, click on it and then click on Click to see More ↓ to get the Nonce number of that transaction.

All the transactions of an ethereum address have a nonce number that increment after each transaction.

Now the concept behind cancelling a pending transaction is to actually send a new transaction with the same Nonce but with a higher fees that the miner will verify and confirm. When this will be done, the previous pending transaction with the same nonce will simply be cancelled and forget by the network because only unique nonce transaction per ETH address can exists.

You should have those informations for going to the next phase :

Your Ethereum address
The Nonce of your blocked pending transaction
MetaMask installed and running with your Ethereum address

How can I send my own custom transaction

The basic configuration of MetaMask doesn't allow us to use custom Nonce, but you can enable that option in the configuration.

Enabling the custom gas settings and custom nonce

Click on this button
The go into the settings
Now click on Advanced
I suggest to enable both Advanced gas controls and Customize Transaction nonce

Sending a custom transaction to fix the pending tx

Once that's done, quit the configuration and now click on the SEND button.
Paste your ETH address, and then add 10 GWEI to the transaction fee gas price to be sure you are above the network average Gas Price so this transaction won't be stuck pending as well. Always verify on Eth Gas Station and use a Gas Price above the FAST recommendation. Leave Gas Limit as it is (21000).

Click on Next when you are done.
In this screen you should be able to set your own custom Nonce if you enable it properly in MetaMask config as explained in the beginning of that article. Write down the Nonce of your blocked pending transaction and click on Confirm.
MetaMask will ask you to sign your transaction and how will depend on if you are using a Ledger or something else. Once you did sign it, the transaction will be sent and if you were above the FAST Gas Price recommendation from Eth Gas Station website it should be confirmed in less than a minute and your blocked pending transaction should now be cancelled.
If you had other pending transaction after that one that are still blocked after this, you will need to repeat the process for each one of them, from the oldest to the newest until you eventually cleared your whole pile of pending transactions.

How can I prevent that from happening again

Regularly keep an eye on the Eth Gas Station website to know the current average Gas Price, and don't always trust pre configured gas price from MetaMask. If you are doing a transaction that is very important, you can always Edit the Gas Price MetaMask is choosing for you and set it to fast, or even a custom one that you decide.

The no hello policy

Mathieu — Thu, 30 Jul 2020 07:25:02 +0000

Original article : https://brainsorting.dev/posts/the-no-hello-policy/

Please Don't Say Just Hello In Chat

2010-07-19 12:32:12 you: Hi
2010-07-19 12:32:15 co-worker: Hello.
# CO-WORKER WAITS WHILE YOU PHRASE YOUR QUESTION
2010-07-19 12:34:01 you: I'm working on [something] and I'm trying to do [etc...]
2010-07-19 12:35:21 co-worker: Oh, that's [answer...]

It's as if you called someone on the phone and said "Hi!" and then put them on
hold!

Please do this instead:

2010-07-19 12:32:12 you: Hi -- I'm working on [something] and I'm trying to do [etc...]
2010-07-19 12:33:32 co-worker: [answers question]

Note that you get help minutes sooner, and you don't make them wait. Instead,
the co-worker can start thinking about your question right away!

You're trying to be polite by not jumping right into the request, like you
would do in person or on the phone. But Chat is neither of those things. Typing
is much slower than talking. Instead of being polite, you are just making the
other person wait for you to phrase your question, which is lost productivity.

The same goes for "Hello -- Are you there?", "Hi Bob -- quick question.", "Do
you have a sec ?", "yt?" and "ping". Just ask the question!

If you feel it's brusque to simply say "Hi" and ask the question, you can do
something like this:

2010-07-19 12:32:12 you: Hi -- if you're not busy I was wondering if I could ask a question. I'm working on [something] and I'm trying to do [etc...]

Additionally, asking your question before getting a reply allows asynchronous
communication. If the other party is away, and you leave before they come back,
they can still answer your question, instead of just staring at a "Hello" and
wondering what they missed.

Some people like to probe with an initial "hello" to verify whether the presence
status shown is true, hoping they can determine whether the recipient is near a device,
then will immediately follow up with a call. Don't do that either.
If someone is able and willing to answer a chat message, it does not mean that they are also available for
a voice or video call.

Instead of sending a call probe, or asking "hey, do you have time for a call?"
(which is better but not great), you can try something like this:

2020-07-08 12:32:12 you: Hi - do you have X min for a quick call to talk about XYZ? [etc...]

This does three things: it time bounds the request, it gives the recipient some context, and
it helps you remember what you wanted to talk about if the recipient can't or doesn't respond
until later.

This version was inspired by the original website nohello.com.
Acknowledgements go to the original anonymous author.

Create a blog with Pelican, hosted on Github/Netlify

Mathieu — Sat, 18 Jul 2020 16:52:30 +0000

Original article : https://brainsorting.dev/posts/create-a-blog-with-pelican/

I hope this article / tutorial will give you the essential knowledge and steps to create and deploy your Pelican static blog on Netlify for free !

Goals

Install Pelican
Create a website running on Pelican
Deploy a Pelican based site to Netlify.com

Prerequisites

Basic knowledge about git and python
Python 3 and git installed on your workstation
VSCode or other IDE

Install Pelican

The first step is to create a python virtual environment on your machine and then install Pelican and other necessary dependencies.

I personally use poetry and the command in your terminal would go this way:

> cd /path-to-your-blog-folder
> poetry init

This command will guide you through creating your pyproject.toml config.

Package name [blog]:
Version [0.1.0]:
Description []:  My personal blog
Author [MattiooFR <*****@*****.com>, n to skip]:
License []:
Compatible Python versions [^3.8]:

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file

# a few more lines telling your about the generated config file..

> poetry shell
> poetry add pelican Markdown typogrify invoke livereload
# install happening...
> pelican-quickstart

Welcome to pelican-quickstart v4.2.0.

This script will help you create a new Pelican-based website.

Please answer the following questions so this script can generate the files
needed by Pelican.

> Where do you want to create your new web site? [.]
> What will be the title of this web site? Your blog title
> Who will be the author of this web site? Your name
> What will be the default language of this web site? [fr] en
> Do you want to specify a URL prefix? e.g., https://example.com   (Y/n) n
> Do you want to enable article pagination? (Y/n) y
> How many articles per page do you want? [10]
> What is your time zone? [Europe/Paris]
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n)
> Do you want to upload your website using FTP? (y/N)
> Do you want to upload your website using SSH? (y/N)
> Do you want to upload your website using Dropbox? (y/N)
> Do you want to upload your website using S3? (y/N)
> Do you want to upload your website using Rackspace Cloud Files? (y/N)
> Do you want to upload your website using GitHub Pages? (y/N)
Done. Your new project is available at ***/***/Blog

> pelican
# says nothing to generate but it will still generate your empty blog files, congratulation !

Ok, now that we have the skeleton of our blog done we can move on to the next part.

You should see an arborescence that looks like this

.
├── content            # this is where your articles written in markdown for eg will be placed
├── output             # your website will be generated in this folder
├── Makefile           # file for automating generating and publishing tasks
├── pelicanconf.py     # config file for the generation of the output
├── publishconf.py     # also a config file for publishing
└── tasks.py           # file also for the automation part

Now go in your content folder and create a file, for the purpose if this tutorial, here is a markdown file article.

Title: Prime number finder in python
Date: 2020-03-21 16:00
Tags: maths, python
Category: maths
Slug: primes-list
Authors: Mathieu
Summary: Find all the prime numbers in a composite number with python.

## Extract all the prime number from a composite number with python

This is a quick article to show you how to create an algorithm to extract all the prime numbers from a composite number in Python.

### Algorithm

    def primes_list(N):
        """
        Extract all the prime numbers
        from a composite number

        Keyword arguments:
        N -- an integer
        Return: a list of prime numbers
        """
        for i in range(N-1, 0, -1):
            if i == 1:
                return [N]
            elif N % i == 0:
                return [int(N/i)] + primes_list(int(i))

### Usage

    print(primes_lists(12))
    > [2,2,3]

The first 7 lines will be more detailed in the next article but they are essential for pelican to generate properly your article and are called the metadata.

On your terminal do the command pelican or invoke build (if you installed the invoke package) to generate the files for your new article, and if you now have a look in your blog folder you should see new folders and files.

Lets have a break with a quick explanation on the invoke build command

While following tutorial to learn myself how to use pelican to create a blog, I faced a few issues and I want to prevent you facing the same, while still understanding why.

The integrated make *** commands produces errors when your blog folder is located in a path that includes spaces so this was the first pain point.
The make build doesn't output anything, the first time I thought there was a problem with my terminal but it was actually working. I don't like when things are unclear so this was a second pain point for me.
The last and ultimate pain point was that the make devserver is just not working. This command is supposed to automatically detect changes in your file and regenerate your blog.

After looking on the revered google, I discovered that a second command can be used. This is invoke but you need to install a separate package, which is why I made you install it at the beginning. With this new package you could do invoke build to build your blog without the path pain point.

If you want to regenerate your blog when a changes in a file is detected, invoke regenerate or pelican --autoreload is your command.

Alright, that was quite a long break but I think it was necessary !

Let's see how your blog looks like no ?

For that you need to use the command invoke serve or pelican --listen in your terminal, if your terminal looks frozen don't worry, it actually works. If you now open your web navigator and go here http://127.0.0.1:8000 your blog should now appear !

Now I will tell you a magical command that require one more package to be installed, it is invoke livereload. If you followed the tutorial, you should already have installed the livereload package.

If you do invoke livereload your blog will be regenerated when a changes is made, AND your browser will be automatically reloaded as well ! Look at that ! Removing the need for you to do cmd + R !

With one terminal windows running your blog will be served, auto regenerated, and your browser will be automatically reloaded each time you save a change in your blog. This is really really useful when you are developing your blog before deploying it to everybody.

Hosting your blog files

Create an account in GitHub if you don't have one yet.

Next, create a repository called "blog_source". This is where you will push all your blog files. Once the repository is made do the following command in your terminal at your blog folder location.

> git init
> git add .
> git commit -m "Initial commit"

# change <your_github_name> in the command down below
> git remote add origin https://github.com/<your_github_name>/blog_source.git
> git push -u origin master

Publishing your static blog

Now that you have a beautiful basic blog locally, the next step is to make it available to everybody right ?

Netlify offer the free service of hosting and deploying a free static page blog, and this what pelican is making 💪🏼, a free static page blog. The procedure is quite straightforward.

Register in Netlify, you can signup with your GitHub account. After you signed up, click on create a new site and select Github as a source. You can accept to give only your blog_source repository to Netlify. In the last step you need to provide the command to build your website in the input labeled build command which is invoke build. The published directory is output.

Netlify require a requirements.txt file to properly build your blog. Enter this command in your terminal to export your poetry dependencies to this required file.

poetry export -f requirements.txt > requirements.txt

Now your blog is almost ready, simply commit and push a new change in your blog, like adding a new article, and Netlify will automatically detect a change in your git repository. It will then build your files and deploy your static blog. In the settings you can specify the name of your blog. I personally decided to buy a domain name so I can have my own url like www.brainsorting.dev instead of www.brainsorting.netlify.com.

The procedure is to directly buy the domain with Netlify, or buy it through https://domains.google/ and then follow the instruction in Netlify to use that domain.

Writing articles

The power of Pelican is that you can write in markdown, reStructuredText or directly HTML and then it will be generated in the same output format, HTML. For writing in Markdown you need to have the parser package installed, which is done with a quick pip install Markdownor poetry add Markdown.

It is really helpful to add images, and to do so when writing in Markdown you need to follow those instructions.

Create a new folder images in your content folder.

Open the pelicanconf.py file and add this line STATIC_PATHS = ['images']. This is telling Pelican to include the folder images in the output when building your blog.

Now you can write ![your_image](/images/your-images.png) in Markdown and get your image displayed.

Choosing a theme

You can choose a pelican theme here. Then store the theme somewhere in your blog folder, create a THEME variable in your pelicanconf.py file and set it to the location where you downloaded your theme in your blog folder.

Installing the Jupyter Plugin

This plugin enables the support for .ipynb file. Create the plugins folder. Run the git submodule add git://github.com/danielfrg/pelican-ipynb.git plugins/ipynb command to add the plugin as git submodule in this folder.

Be sure to have these lines in your pelicanconf.py :

MARKUP = ('md', 'ipynb')

PLUGIN_PATH = './plugins'
PLUGINS = ['ipynb.markup']

Copy the notebook file into the content folder.

Create a file that has the same name as your notebook, but with the extension .ipynb-meta.

Add the following content to the ipynb-meta file, but change the fields to match your own post:

Title: Jupyter notebook
Slug: jupyter-post
Date: 2020-07-11 20:00
Category: posts
Tags: python pelican
author: mathieu dugue
Summary: Test jupyter notebook

Each time you want to add a new notebook you need to repeat those steps.

Useful Modules

References

Using environment variables in a Flask + Heroku project

Mathieu — Tue, 05 May 2020 16:36:07 +0000

You can also read that article on my blog or on medium !

Using environment variables is fundamental in a project. This is how you tell your app if you are running in production or locally for example. This is where you also store more sensible information like SECRET_KEY or API credentials. Storing those directly in your web app code can be easy at first, but it is not safe when you will push your code in production, so taking good habits from the beginning is a good idea.

Before jumping in the topic of configuring environment variables, I will first make you set up and deploy a basic app.

Flask

In this project I use Flask. Create a folder for your app and a new virtual environment (check out poetry if you don't know what it is). Once your virtual environment is running, we need to install a few dependencies first :

# if you use poetry as virtual environment manager
# use the command 'poetry add' instead of 'pip install'

pip install flask gunicorn

Flask is the web server running with python, and Gunicorn is what will basically run our web server on Heroku when we will deploy our app.

Lets first set up a basic app and create a file app.py in your folder :

import os
from flask import Flask, render_template

app = Flask(__name__)


@app.route('/')
def index():
    greeting = "Hello"
    try:
        excited = os.environ['EXCITED']
        greeting = greeting + "!!!!!"
    except:
        pass

    return render_template("index.html", greeting=greeting)

As you see we will render an index.html so create that file too inside a templates folder and paste this code inside :

<!doctype html>
<html>
    <head>
        <title>My App</title>
    </head>

    <body>
        {{ greeting }}
    </body>
</html>

Before running the web app locally we need to set two variable in your terminal so Flask knows what to do exactly :

export FLASK_ENV=development
export FLASK_APP=app.py
export EXCITED=True

Lets run our app locally with flask run . As you can see we are greeted like expected, with all the '!!!!', but I had to export the variable in my terminal. Every time you close your terminal you need to do that again. Not very efficient.

Heroku

Now if we want to deploy our app on Heroku we need to do a few things.

Create a Procfile at the root of your folder. Paste this code inside :
```
web: gunicorn app:app
```

We need to export all the python dependencies in a requirements.txt file :

pip freeze > requirements.txt

# if you use poetry you can do as following
poetry export -f requirements.txt > requirements.txt

Install Heroku CLI on your machine and then login on your Heroku account (here to register):

# if you are on mac and use homebrew
brew tap heroku/brew && brew install heroku

# you can also use npm
npm install -g heroku

Once Heroku is available on your terminal, we can create your Heroku App :
```
heroku create <name_of_your_app>
```
Now if you check your Heroku Dashboard in the browser, you'll see an application with that name. But it doesn't have our code or anything yet - it's completely empty. Let's get our code up there.
The next step is initializing git in your repository, and add the Heroku remote in your git repository :
```
git init
heroku git:remote -a <name_of_your_app>
```
Now before pushing our app on Heroku, we need to set that EXCITED variable to true. You can do that on the web interface of Heroku, or using the CLI with :
```
heroku config:set EXCITED=True
```

To push our web app to Heroku we can simply do :

git add .
git commit -m"deploying app on heroku"
git push heroku master

Now if you look at https://name_of_your_app.heroku.com you should have a nice excited greeting message : Hello !!!!

Environment Variable

Alright, thank you Mathieu, but how is that suppose to teach us how to manage environment variable ?

Well, now that you are set up properly, let me introduce the .env and .flaskenv files. By convention, the .flaskenv is where you store your variables related to your flask configuration, such as the type of environment, or the files that contains your flask app. For this example we will write those lines inside this file :

#.flaskenv file

FLASK_APP=app.py
FLASK_ENV=development

Now the .env file contains the sensible variable information that your app needs to run. This file stay locally and you must include it in your .gitignore to avoid sharing sensible informations. For the purpose of this tutorial we will just include one variable :

#.env file

EXCITED=True

Your folder structure should look something like this :

.
├── templates
    └── index.html
├── .env
├── .flaskenv
├── .gitignore
├── Procfile
├── app.py
└── requirements.txt

Now we have two different use case possible. If you want to use flask to run your app locally you need to install one more dependencies

pip install python-dotenv

# with poetry use
poetry add python-dotenv

You don't need to do anything else, thanks to this new package, flask will automatically detect your two new files and will load their variables in the app context.

If instead of using flask to run your app locally you prefer to use heroku local web then you don't need to install python-dotenv, Heroku will detect the .env file by itself.

Conclusion

We saw how to implement a behavior that allows us to protect our sensible information by putting them in external files that wont be pushed to a public git repository. In the same time our app will work seamlessly when deployed on Heroku, if you set up the same variables in your .env files on the config of your Heroku app (with the web interface or the CLI).

You can find all the code of this tutorial here.

Publish a package on PyPi using Poetry

Mathieu — Tue, 05 May 2020 16:36:05 +0000

You can also read that article on my blog or on medium !

First thing first, you need Poetry if you don't have it already.

Poetry is the new standard for creating and managing virtual environment for your Python project. It is also a Python dependency management tool that is working differently as pip. It uses the new standard pyproject.toml decided by the Python Packaging Authority with PEP-518. This file merges all the previous config files that were necessary before, setup.py, requirements.txt, setup.cfg, MANIFEST.in et Pipfile, in one unique file to rule them all ! Ok, enough of Lord of the Ring.

I advise you to follow along with the documentation of poetry open.

Install Poetry

curl -sSL https://raw.githubusercontent.com/sdispater/poetry/master/get-poetry.py | python

Feel free to look here for more instructions. Updating Poetry is very easy by the way poetry update.

Create the package you want to publish on PyPi

Poetry has a nice command that can create your project tree at once poetry new <package_name>.

/<package_name>
├── README.rst # I personnaly change it to .md as I prefer writing in Markdown
├── <package_name>
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_package_name.py

You will need to add things to the generated pyproject.toml file, feel free to check the poetry documentation to see all the options.

[tool.poetry]
name = "vspoetry"
version = "0.1.0"
description = "Description of your package"
authors = ["MattiooFR <dugue.mathieu@gmail.com>"]
keywords = ["keyword", "another_keyword"]
readme = "README.md"
license = "MIT"
homepage = "https://github.com/MattiooFR/package_name"
repository = "https://github.com/MattiooFR/package_name"
include = [
    "LICENSE",
]

[tool.poetry.dependencies]
python = "^3.5"

[tool.poetry.dev-dependencies]

[tool.poetry.scripts]
cli_command_name = 'package_name:function'

[build-system]
requires = ["poetry>=0.12"]
build-backend = "poetry.masonry.api"

The beginning of the file is pretty straightforward. Lets focus on those three part :

[tool.poetry.dependencies]: This is where you can list all the dependencies that your package needs to work. It's like the old requirements.txt file. You can do it by hand and then call the command poetry install to install them all for your package development and working purposes. If you use poetry add <dependency_name> (equivalent to the pip install <dependency_name>), poetry will add it there for you.
[tool.poetry.dev-dependencies]: If you need development dependencies, that's where they go. Again, you can also install them with poetry add <dependency_name> --dev (or -D) and poetry will also put that in the right place in your pyproject.toml file.
[tool.poetry.scripts]: This last block is very important if you want your package to have script callable from the terminal.
```
script_name = '{package_name}:{function_name}'
```

By the way, if you still need to have a requirements.txt with all the dependencies (if you use Heroku for example), you can easily have it with this command :

poetry export -f requirements.txt > requirements.txt

Build your package

When your package is ready, simply do poetry build to create the package files

❯ poetry build
Building package_name (0.1.0)
 - Building sdist
 - Built package_name-0.1.0.tar.gz

 - Building wheel
 - Built package_name-0.1.0-py3-none-any.whl

You can test your package by doing

pip install <path_to_package_name-0.1.0-py3-none-any.whl>

If everything works, congrats ! Now lets publish it to PyPi so others can use your great package too.

Publish your package

Before publishing you should first create an account on PyPi. You can also register an account on TestPyPi if you want publishing on a test repository before trying on the official one.

Your package need to be built, so first run poetry build if you haven't done it already.

Then simply run poetry publish and your package will be publish on PyPi :

❯ poetry publish

Publishing vspoetry (0.1.0) to PyPI
Username: Mattioo
Password:
 - Uploading vspoetry-0.1.0-py3-none-any.whl 100%
 - Uploading vspoetry-0.1.0.tar.gz 100%

If you need to update your package, simply increment the version in the pyproject.toml file and use poetry publish (after you build the new package with poetry build).

Once you have done that you can then install your package :

pip install <your_package>

poetry add <your_package> # but lets be honest now you use Poetry so you would do this !

Congrats on publishing your package on PyPi and experiencing the simplicity of using a tool like Poetry.

Happy coding !

End notes

I actually just published my first package, vspoetry, while writing this tutorial. It is a package that add the vspoetry script command to my terminal and this simply add the path of the current poetry virtual environment of the project to VScode settings.json. This tells to VScode where to grab the project python venv because VScode does not do that automatically yet.

Create a blog using Nikola static website generator

Mathieu — Tue, 05 May 2020 16:36:03 +0000

You can also read that article on my blog or on medium !

If you don't know what is Nikola, it is a static website/blog generator (like gatsby and other tools). It's written in Python and it is working out of the box for rendering markdown, rst, latex math formula and jupyter notebook files.

I like to understand what I am using, and pushing it to some limits to really get what I want from it, and making a blog with Nikola was no exception. Here I tried to summarize all the informations I found, and all the experimentation I did. I hope you'll enjoy ! 🙏🏼

1) Installation

The first step is to have Python 3 installed on your computer, I recommend using virtual environment management.

Once you have create your virtual environment :

pip install --upgrade pip setuptools wheel
pip install --upgrade "Nikola[extras]"

2) Create the blog

After installing Nikola, creating your site will be very easy, just use the command nikola init <directory_name>. You can add the --demo argument if you want a website built with demo content.

All the configurations are done in a single conf.py file, at the root of your blog folder.

You can now build your site and see how it looks like. Use the command nikola auto to use a server with automatic rebuilds when changes is detected in your files. Visit http://128.0.0.1:8000 to see your site.

3) Add a Post

Now if you want to add a post in your blog you should use the command nikola new_post(the default use reStructuredText format, add -f markdown if like me you prefer to write in markdown). The CLI will ask for the title of your blog post and then create the file in the folder posts/*.md.

4) Enable Jupyter Notebook file format

Just add *.ipynb as recognizable formats:

POSTS = (
    ("posts/*.rst", "blog", "post.tmpl"),
    ("posts/*.md", "blog", "post.tmpl"),
    ("posts/*.txt", "blog", "post.tmpl"),
    ("posts/*.html", "blog", "post.tmpl"),
    ("posts/*.ipynb", "blog", "post.tmpl"), # new line
)
PAGES = (
    ("pages/*.rst", "", "page.tmpl"),
    ("pages/*.md", "", "page.tmpl"),
    ("pages/*.txt", "", "page.tmpl"),
    ("pages/*.html", "", "page.tmpl"),
    ("pages/*.ipynb", "", "page.tmpl"), # new line
)

You can create a blog post with nikola new_post -f ipynb or add your jupyter notebook in your posts folder. Don't forget to add and configure these line in the metadata of your jupyter notebook file if you don't let nikola create the file for yourself :

"nikola": {
   "category": "",
   "date": "2020-03-28 16:27:51 UTC+01:00",
   "description": "",
   "link": "",
   "slug": "jupyter-notebook-test",
   "tags": "",
   "title": "Jupyter Notebook Test",
   "type": "text"
  }

5) Using Markdown for your post

Nikola handle markdown files by default. The meta are auto generated when you use nikola new_post but I prefer to do it differently. Add the markdown.extensions.meta to your conf.py file.

MARKDOWN_EXTENSIONS =
 ['markdown.extensions.fenced_code',
  'markdown.extensions.codehilite',
  'markdown.extensions.extra',
  'markdown.extensions.meta']

Now you can simply add these line on top of your markdown files, in a pelican style, to indicate Nikola all the information it needs to build your post :

Title: Test post in markdown
Date: 2020-04-01
Slug: test-post
Tags: markdown, test
Categories: Tutorial

In my situation I decided to use pandoc instead of the default markdown compiler. I did this because I often have code blocks nested in numbered or bullet list and the default markdown compiler does not render those properly. It also looses the numbered list sometimes whereas pandoc is doing an absolute great job. Thanks to this great blog post that was explaining how to do it !

To use pandoc instead of the default markdown you need to first install it. You can use brew install pandoc if you have a mac, or look here for more instructions. Then you can change those lines in the conf.py :

COMPILERS = {
    "rest": ('.rst', '.txt'),
    # "markdown": ('.md', '.mdown', '.markdown'),
    "textile": ('.textile',),
    "txt2tags": ('.t2t',),
    "bbcode": ('.bb',),
    "wiki": ('.wiki',),
    "ipynb": ('.ipynb',),
    "html": ('.html', '.htm'),
    # PHP files are rendered the usual way (i.e. with the full templates).
    # The resulting files have .php extensions, making it possible to run
    # them without reconfiguring your server to recognize them.
    "php": ('.php',),
    # Pandoc detects the input from the source filename
    # but is disabled by default as it would conflict
    # with many of the others.
    "pandoc": ('.md', 'txt'),
}
...
PANDOC_OPTIONS = ['-f', 'gfm', '--toc', '-s']

See how I commented the markdown compiler and uncommented pandoc for .md files. The last two PANDOC_OPTIONS (--toc and -s) are used for automatically generating a Table of Content on the HTML generated output.

Once you use pandoc for compiling your markdown file, for creating a new blog post in markdown you need yo use this command nikola new _post -f pandoc and not markdown anymore.

Adding solely the pandoc as markdown compiler is unfortunately not enough because we lose the ability to use the CODE_COLOR_SCHEME = monokai option in conf.py. One solution is to use pandoc generated css for one of its code highlight theme (kate in my case).

Create a custom.css file in files/assets/css/ as explained here and add this css code :

code {white-space: pre-wrap;}
span.smallcaps {font-variant: small-caps;}
span.underline {text-decoration: underline;}
div.column {display: inline-block; vertical-align: top; width: 50%;}

a.sourceLine { display: inline-block; line-height: 1.25; }
a.sourceLine { pointer-events: none; color: inherit; text-decoration: inherit; }
a.sourceLine:empty { height: 1.2em; position: absolute; }
.sourceCode { overflow: visible; }
code.sourceCode { white-space: pre; position: relative; }
div.sourceCode { margin: 1em 0; }
pre.sourceCode { margin: 0; }
@media screen {
div.sourceCode { overflow: auto; }
}
@media print {
code.sourceCode { white-space: pre-wrap; }
a.sourceLine { text-indent: -1em; padding-left: 1em; }
}
pre.numberSource a.sourceLine
  { position: relative; }
pre.numberSource a.sourceLine:empty
  { position: absolute; }
pre.numberSource a.sourceLine::before
  { content: attr(data-line-number);
    position: absolute; left: -5em; text-align: right; vertical-align: baseline;
    border: none; pointer-events: all;
    -webkit-touch-callout: none; -webkit-user-select: none;
    -khtml-user-select: none; -moz-user-select: none;
    -ms-user-select: none; user-select: none;
    padding: 0 4px; width: 4em;
    background-color: #ffffff;
    color: #a0a0a0;
  }
pre.numberSource { margin-left: 3em; border-left: 1px solid #a0a0a0;  padding-left: 4px; }
div.sourceCode
  { color: #1f1c1b; background-color: #ffffff; }
@media screen {
a.sourceLine::before { text-decoration: underline; }
}
code span. { color: #1f1c1b; } /* Normal */
code span.al { color: #bf0303; background-color: #f7e6e6; font-weight: bold; } /* Alert */
code span.an { color: #ca60ca; } /* Annotation */
code span.at { color: #0057ae; } /* Attribute */
code span.bn { color: #b08000; } /* BaseN */
code span.bu { color: #644a9b; font-weight: bold; } /* BuiltIn */
code span.cf { color: #1f1c1b; font-weight: bold; } /* ControlFlow */
code span.ch { color: #924c9d; } /* Char */
code span.cn { color: #aa5500; } /* Constant */
code span.co { color: #898887; } /* Comment */
code span.cv { color: #0095ff; } /* CommentVar */
code span.do { color: #607880; } /* Documentation */
code span.dt { color: #0057ae; } /* DataType */
code span.dv { color: #b08000; } /* DecVal */
code span.er { color: #bf0303; text-decoration: underline; } /* Error */
code span.ex { color: #0095ff; font-weight: bold; } /* Extension */
code span.fl { color: #b08000; } /* Float */
code span.fu { color: #644a9b; } /* Function */
code span.im { color: #ff5500; } /* Import */
code span.in { color: #b08000; } /* Information */
code span.kw { color: #1f1c1b; font-weight: bold; } /* Keyword */
code span.op { color: #1f1c1b; } /* Operator */
code span.ot { color: #006e28; } /* Other */
code span.pp { color: #006e28; } /* Preprocessor */
code span.re { color: #0057ae; background-color: #e0e9f8; } /* RegionMarker */
code span.sc { color: #3daee9; } /* SpecialChar */
code span.ss { color: #ff5500; } /* SpecialString */
code span.st { color: #bf0303; } /* String */
code span.va { color: #0057ae; } /* Variable */
code span.vs { color: #bf0303; } /* VerbatimString */
code span.wa { color: #bf0303; } /* Warning */

Now your code blocks should be highlighted. It's up to you to custom it further to change the color background or stuff like this.

I also wanted to style the table of content :

.p-summary.entry-summary #TOC {
  display: None; /* disable showing the TOC in my blog home page teasers */
}

#TOC {
  background-color: #e9f8f8;
  border-radius: 3px;
  padding: 18px 0px 1px 6px;
  margin-bottom: 20px;
}

6) Pages vs Posts

Nikola has two type for entries on your website, POSTS and PAGES.

POSTS

These are your blog posts. POSTS are added to feeds, indexes, tag lists and archives.

7) Customizing the navigation bar

Customization of the navigation top bar is done, again, in the conf.py file.

NAVIGATION_LINKS = {
    DEFAULT_LANG: (
        ("/resume/", "Resume"),
        ("/cheatsheet/", "Cheatsheet"),
        ("/archive/", "Archive"),
    )
}

This is an example of how I've done mine.

8) Indexes as a list of links or list of posts

Nikola allows you to categorize posts in a number of ways such as category, tags, archives, and authors. For each means of categorizing, an associated index page is generated so that viewers can see all available posts (_PAGES_ARE_INDEXES = True) or links associated to that category (_PAGES_ARE_INDEXES = False).

You can choose for these indexes to produce a list of the full posts (or showing teasers instead of the full post) or a list of links to each post. Depending on your needs, you can change any of the following index settings in conf.py to True.

CATEGORY_PAGES_ARE_INDEXES = False
TAG_PAGES_ARE_INDEXES = False
ARCHIVES_ARE_INDEXES = False
AUTHOR_PAGES_ARE_INDEXES = False

This is what makes Nikola so customizable. For example, since there are less Categories, and you may have more posts under each category, you might want them as a list of links. Alternatively, with Tags there are usually more of them, so less posts under each Tag so you want a list of posts.

9) Enable a comment system

Because static sites do not have databases, you need to use a third-party comment system as documented on the official doc.

Sign up for an account on https://disqus.com/.
On Disqus, select "Create a new site" (or visit https://disqus.com/admin/create/).
During configuration, take note on the "Shortname" you use. Other configs are not very important.
At "Select a plan", choosing the basic free plan is enough.
At "Select Platform", just skip the instructions. No need to insert the "Universal Code" manually, as it is built into Nikola. Keep all default and finish the configuration.

In conf.py, add your Disqus shortname:

COMMENT_SYSTEM = "disqus"
COMMENT_SYSTEM_ID = "[disqus-shortname]"

Deploy to GitHub and now the comment system should be enabled.

10) Deploying your website

My workflow is separated in two parts :

Github Pages
Netlify

Github Pages

I decided to host my blog files on GitHub and use their free service, GitHub Pages, for deploying my blog on this address https://mattioo.github.io.

For doing that you will need to have a GitHub account, and enable GitHub Pages. Once you created your repository as explained for GitHub Pages, initialize GitHub in your source directory

git init .
git remote add origin https://github.com/<USER_NAME>/<USER_NAME>.github.io

The conf.py should have the following settings.

GITHUB_SOURCE_BRANCH = 'src'
GITHUB_DEPLOY_BRANCH = 'master'
GITHUB_REMOTE_NAME = 'origin'
GITHUB_COMMIT_SOURCE = True

Create a .gitignore file with the following entries as a minimum. You may use gitignore.io to generate a suitable set of .gitignore entries for your platform by typing in the relevant tags (e.g., mac,nikola,jupyternotebooks).

cache
.doit.db
__pycache__
output
ipynb_checkpoints
*/.ipynb_checkpoints/*

By using the nikola github_deploy command, it will create a src branch that will contain your contents (i.e., *.ipynb, *.md, and a master branch that will only contain your html output pages that are viewed by the browser.

nikola github_deploy

Netlify extra steps

Because of all these reasons I wanted to use Netlify for deploying my blog with a custom domains, www.brainsorting.dev. I simply configured a trigger on Netlify to start building my blog when it detects any new push on my GitHub blog repository. It is as simple as said, everything kind of works out of the box and the service provided by Netlify has been very stable and giving me very good SEO statistics.

11) Archives

Nikola has many options for how you would display your archive of posts. I've kept it pretty simple on my end.

# Create per-month archives instead of per-year
CREATE_MONTHLY_ARCHIVE = False
# Create one large archive instead of per-year
CREATE_SINGLE_ARCHIVE = False
# Create year, month, and day archives each with a (long) list of posts
# (overrides both CREATE_MONTHLY_ARCHIVE and CREATE_SINGLE_ARCHIVE)
CREATE_FULL_ARCHIVES = False
# If monthly archives or full archives are created, adds also one archive per day
CREATE_DAILY_ARCHIVE = False
# Create previous, up, next navigation links for archives
CREATE_ARCHIVE_NAVIGATION = False
ARCHIVE_PATH = "archive"
ARCHIVE_FILENAME = "archive.html"

12) Content Footer

I use the recommended license :

LICENSE = """
<a rel="license" href="https://creativecommons.org/licenses/by-nc-sa/4.0/">
<img alt="Creative Commons License BY-NC-SA"
style="border-width:0; margin-bottom:12px;"
src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png"></a>"""

You might want to have a specific message (i.e., license, copyright, contact e-mail address) at the footer of every page and this is where to do it. In this case I've added a Mailchimp link so that readers can subscribe to my page.

CONTENT_FOOTER = '''
<center>
''' + MAILCHIMP_SIGNUP + '''
<br>
Contents &copy; {date} <a href="mailto:{email}">{author}</a> <a href="https://dev.to/mattioo"><i class="fab fa-dev" title="mattioo's DEV Profile"></i> </a> - Powered by <a href="https://getnikola.com" rel="nofollow">Nikola</a> {license} - favicon <a href="https://www.flaticon.com/">FlatIcon</a>
</center>
<br>
'''

13) Rendering math equations

I have enabled KaTeX because its prettier with the $...$ syntax as thats more similar to LaTeX.

USE_KATEX = True
KATEX_AUTO_RENDER = """
delimiters: [
    {left: "$$", right: "$$", display: true},
    {left: "\\\\[", right: "\\\\]", display: true},
    {left: "\\\\begin{equation*}", right: "\\\\end{equation*}", display: true},
    {left: "$", right: "$", display: false},
    {left: "\\\\(", right: "\\\\)", display: false}
]
"""

14) Implementing Google tools

Google search

I've enabled Google search form to search in my site.

SEARCH_FORM = """
 <form method="get" action="https://www.google.com/search" class="form-inline my-2 my-lg-0" role="search">
 <div class="form-group">
 <input type="text" name="q" class="form-control mr-sm-2" placeholder="Search">
 </div>
 <button type="submit" class="btn btn-secondary my-2 my-sm-0">
    <i class="fas fa-search"></i></button>
 </button>
 <input type="hidden" name="sitesearch" value="%s">
 </form>
""" % SITE_URL

Google Analytics

Google Analytics can be added to the bottom of <body> to function.

BODY_END = """
<!-- Global Site Tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_TRACKING_ID"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', '<YOUR GOOGLE ANALYTICS IDENTIFIER>');
</script>
"""

15) Customizing your blog

Theme & Template customization

To create a new theme, we can use the following command which will create a new folder in themes called brainsorting. It is using the mako templating engine and the parent theme is bootstrap4. We don't necessarily want to create a theme from scratch, so we base it off the bootstrap4 theme (or whatever theme you want) and make the adjustments that we want.

nikola theme --new=brainsorting --engine=mako --parent=bootstrap4

We can also copy over any templates from the parent theme where we want to make modifications by using the following command :

nikola theme --copy-template=base.tmpl

If you want to examine all the components of the parent theme (i.e., bootstrap4 in my case), the following command will give you the path to the parent theme for you to explore.

nikola theme -g bootstrap4

The full list of templates is shown below:

.
├── authors.tmpl
├── base_helper.tmpl
├── base.tmpl
├── gallery.tmpl
├── index_helper.tmpl
├── listing.tmpl
├── pagination_helper.tmpl
├── post.tmpl
├── tags.tmpl
└── ui_helper.tmpl

For example if you want to make the nav bar sticky at the top, so that when readers scroll downwards, they can still access the menu bar, you need to update the base.tmpl file as shown below with the command sticky-top. To get the base.tmpl file in your template folder use nikola theme --copy-template=base.tmpl.

<nav class="navbar navbar-expand-md sticky-top mb-4

Setting your favicon

Pick an icon and store it in the folder '/file/', then edit the conf.py as follows :

FAVICONS = (
    ("icon", "/brain.png", "128x128"),
)

Tweaking the CSS

This is quite easy and can be done by dropping a custom.css document here files/assets/css/custom.css. This will be loaded from the <head> block of the site when built.

If you really want to change the pages radically, you will want to do a custom theme.

Files and Listings

This two folders are used to transfer any file or code file to the output folder (your generated website). By default, putting anything in the files folder will be available in the root of your website. Anything in listings or subfolder will be available in output/listings. This last folder allows user to view and download any code file you put in this.

Date formatting

You can customize how the timestamp are displayed on your blog posts.

DATE_FORMAT = 'yyyy-MMM-dd'
DATE_FANCINESS = 2

I like to set it like this to have a more human friendly reading with dates displayed like "3 months ago". Hovering the date with the mouse display the exact date.

Using mailchimp for user to subscribe

Mailchimp allows you to run e-mail campaigns and contact subscribers when you have new content on your site. See Getting Started with Mailchimp for more detailed instructions.

After you created your account you can create your signup form and get a code that looks like this one. Create a MAILCHIMP_SIGNUP variable in conf.py and paste this code :

MAILCHIMP_SIGNUP = """
<!-- Begin Mailchimp Signup Form -->
<div id="mc_embed_signup">
<form action="<YOUR MAILCHIMP IDENTIFIER>" method="post" id="mc-embedded-subscribe-form" name="mc-embedded-subscribe-form" class="validate" target="_blank" novalidate>
    <div id="mc_embed_signup_scroll">
    <label for="mce-EMAIL">Subscribe</label>
    <input type="email" value="" name="EMAIL" class="email" id="mce-EMAIL" placeholder="email" required>
    <!-- real people should not fill this in and expect good things - do not remove this or risk form bot signups-->
    <div style="position: absolute; left: -5000px;" aria-hidden="true"><input type="text" name="b_3ffb6593478debd1efe5bf3e7_e432d28210" tabindex="-1" value=""></div>
    <div class="clear"><input type="submit" value="Subscribe" name="subscribe" id="mc-embedded-subscribe" class="button"></div>
    </div>
</form>
</div>

<!--End mc_embed_signup-->
"""

Loading bar

To make use of the pace.js loading library I added this code in the base_helper.tmpl file :

# below the <title> in the base_helper.tmpl file

{% if use_pace %}
    <script src="/assets/js/pace.min.js"></script>
    <link href="/assets/css/pace.css" rel="stylesheet" />
{% endif %}

I then activate it with in the conf.py settings :

GLOBAL_CONTEXT = {
    "use_pace": True,
}

Remove .html suffix from archive.html

This is just a small annoyance, but by default, the archive is located in /archive.html. If you want it to be in /archive/, add the following lines to your conf.py:

ARCHIVE_PATH = "archive"
ARCHIVE_FILENAME = "index.html"

Remember to also fix the navigation links:

NAVIGATION_LINKS = {
    DEFAULT_LANG: (
        ("/pages/resume/", "My Resume"),
        ("/pages/cheatsheet/", "Cheat Sheet"),
        ("/archive/", "Archive"),
    ),
}

Short blog post teaser in index page

The index.tmpl will generate a list of posts associated to the tag/category/year/author. This index can either be the entire post or post with just a teaser. To just show a teaser of the post, set conf.py as follows:

INDEX_TEASERS = True

Don't forget to write in your post file where is the end of the teaser, in Markdown or html or ipynb do like this :

<!-- TEASER_END -->

In reStructuredText, select the end of your teasers with:

.. TEASER_END

If you are using teasers, the default is a Read more... link to access the full post. To make it more informative, you can have statements such as XX minute read... in conf.py as shown below.

INDEX_READ_MORE_LINK = '<p class="more"><a href="{link}">{reading_time} minute read…</a></p>'
FEED_READ_MORE_LINK = '<p><a href="{link}">{read_more}…</a> ({min_remaining_read})</p>'

16) Optimizing your blog

Filters

I want to be sure that all the files on my blog are optimized (such as .html, .js, .jpeg, .png, .css) so I am making use of the filters functionality.

In my conf.py I have the following settings for FILTERS :

FILTERS = {
   ".html": ["filters.typogrify"],
   ".css": ["filters.yui_compressor"],
   ".jpg": ["jpegoptim --strip-all -m75 -v %s"],
   ".png": ["filters.optipng"]
}

For them to work I need to have typogify, yui_compressor, jpegoptim, and optipng installed on my machine. Those instructions are for mac using homebrew:

brew install yuicompressor
brew install optipng
brew install jpegoptim
poetry add typogrify # or "pip install typogrify" if you don't use poetry

Posting automatically on Medium

To publish your Nikola posts on Medium there is this plugin.

You just need to install it with this command :

nikola plugin -i medium

Add a medium.json file in your blog folder with a generated access token that you can get here :

{
    "TOKEN": "your_token_here",
}

Then simply add the metadata markdown : yes in the blog post you want to publish on medium and run the command :

nikola medium

Posting automatically on Dev.to

To publish your Nikola posts on Dev there is this plugin.

You just need to install it with this command :

nikola plugin -i devto

Add a devto.json file in your blog folder with a generated access token that you can get here :

{
    "TOKEN": "your_token_here",
}

Then simply add the metadata devto : yes in the blog post you want to publish on medium and run the command :

nikola devto

Other plugin I didn't try

similarity : Find posts that are similar to the one being read. Requires install of Natural Language Processing packages such as gensim.

Conclusion

That's it for the big tutorial. I hope I was precise enough for giving you all the tools to make a blog very much like you want it. Some part of that article were very inspire (if not copy/pasted for some stuff) from resources down below that helped me a LOT to understand everything I need to understand to reach a result that I like with my blog. My next step will be to automate as much things as possible, you'll know it in a new article when I will have achieve it 😄

Google group to discuss about Nikola : https://groups.google.com/forum/#!forum/nikola-discuss

Resources

https://getnikola.com/handbook.html

https://getnikola.com/getting-started.html

https://nikola.readthedocs.io/en/latest/manual

https://jiaweizhuang.github.io/blog/nikola-guide/

http://www.jaakkoluttinen.fi/blog/how-to-blog-with-jupyter-ipython-notebook-and-nikola/

https://randlow.github.io/posts/python/create-nikola-coding-blog/

Themes

https://themes.getnikola.com/v7/mdl/

https://hackerthemes.com/bootstrap-themes/

https://bootswatch.com/