2020 Pelican Quicktutorial

Title: Pelican setup gist  
Description: What are the steps to get blog like this one up and running?

You can find this as a gist [here](https://gist.github.com/mocquin/6b79794f2edb87fc671f28f0d2aeb6c1)

For this, you'll need basic knowledge of pip, terminal, virtualenv, python, git, and github. 

Disclaimer : this is not a tutorial, this a quick recipe that worked for me. I voluntarly skip most of the explication part.

```
mkdir blog
cd blog
python3 -m venv blog_venv
source blog_venv/bin/activate
pip install pelican markdown
```
Once all the tools are installed, create a pelican project : 
```
pelican-quickstart
```
Then the pelican wizard helps you quickstart your project :
```
> Where do you want to create your new web site? [.] 
> What will be the title of this web site? Wicked blog
> Who will be the author of this web site? mocquin
> What will be the default language of this web site? [fr] 
> 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) n
> What is your time zone? [Europe/Paris] 
> Do you want to generate a tasks.py/Makefile to automate generation and publishing? (Y/n) n
Done. Your new project is available at /path/to/blog
```
At this point, the folder structure would be : 
```terminal
> tree -L 1
.
├── blog_venv
├── content
├── output
├── pelicanconf.py
└── publishconf.py
```
Let's create a git repo, and work on a branch called "dev" :
```
git init
git checkout -b dev
```
And create a .gitignore file to not track the venv folder : 
```
echo "blog_venv/
*.ipynb_checkpoints
__pycache__/
pelican-plugins/
pelican-themes/
output/
" > .gitignore
```
Commit :
```
git add .
git commit -m "initial commit"
```

# Create markdown content and test the setup
Create a markdown file in the content folder :
```
cd content
touch first_post.md
```
Then copy this content in the file and save it : 
```
Title: First post with Pelican!

This is your first post with Pelican, generated with markdown.
```
Then go back to the main folder with ```cd ..```, locate the `pelicanconf.py` file and add at the end :
```
DEFAULT_DATE = "fs"
IGNORE_FILES = ['.ipynb_checkpoints']
```
This allows to ignore unwanted ipynb_checkpoints files/folders to be converted by pelican, and allow you not to define any date metadata in your posts - it will use the file system "fs" date by default. Test the whole installation with : 
```
pelican -l -r

-> Modified: content, theme, settings. re-generating...
Done: Processed 1 article, 0 drafts, 0 pages, 0 hidden pages and 0 draft pages in 0.19 seconds.
```
and open ```localhost:8000``` in your favorite browser. You should see you markdown post.
Stop the server with ```CTRL+C```.


# Add theme and plugins
Let's add themes and plugins for pelican. I here use git submodules. In the main folder (this may take a while):
```
git submodule add https://github.com/getpelican/pelican-themes.git pelican-themes
```
and 
```
git submodule add https://github.com/getpelican/pelican-plugins.git pelican-plugins
```
Finally, do (this may take a while):
```
git submodule update --init --recursive
```

In the ```pelicanconf.py```, uncomment the line to
```
RELATIVE_URLS = True
```
and add somewhere in the file 
```
THEME = "./pelican-themes/bold/"
```
to apply the theme of your choice. You can see the themes at [http://www.pelicanthemes.com/](http://www.pelicanthemes.com/)

Check the theme is functionning with 
```
pelican -r -l
```
and check your ```localhost:8000```.

Now to add math-latex and notebook supports, add the following lines to the pelicanconfg.py : 
```
MARKUP = ('md', 'ipynb')
PLUGIN_PATHS = ['./pelican-plugins']
PLUGINS = ['ipynb.markup', 'render_math']
IPYNB_USE_METACELL = True
```
We also need additional packages to make the ipynb plugin work. Do :
```
pip install jupyter ipython nbconvert
```
Now create a markdown with latex content. Place the following content in `content/latex_in_md.md`:
```
Title: Testing latex in md

# Let's do this
This is inline latex in markdown $E_p = \frac{h_p c}{\lambda}$
This is block latex in markdown :
$$exp(x)=\sum_{n=0}^{+\infty}\frac{x^n}{n!}$$
```
Check the math rendering is working by looking at your post with 
```
pelican -l -r
```
Note : the plugin only work when your are on the page of the article, not on the main page.
Quit the preview mode with `CTRL+C`.
Now create a ipynb with the following content in the first cell, which must be markdown : 
```
- title: My notebook
- date: 2020-02-17
```
Note : the pelican setting DEFAULT_DATE that we added earlier doesn't work with ipynb, so we HAVE to specificy a date.
Then, add content in your notebook (code cells, arrays, plots), and save it.
Now check your notebook is rendering properly with `pelican -l -r`.

At this point, you should have a working local website. Let's commit before moving on :
```
git add content .gitignore pelicanconf.py .gitmodules
git commit -m "initial content and conf"
```
Now it's time to upload online. We'll be using github pages.
Go to Github, and create a new repo called `<username>.github.io` with your username (follow exactly that syntax or it won't work). Copy the link of the repo, and then add this repo as remote to your local project : 
```
git remote add origin https://github.com/<username>/<username>.github.io.git
```
Now create a master branch in your local repo : 
```
git branch master
```
Go to the `publisconf.py`, and add 
```
DELETE_OUTPUT_DIRECTORY = False
SITEURL = 'https://<username>.github.io'
RELATIVE_URLS = False
```
with your username.
Now generate the full website with
```
pelican content -o output -s publishconf.py
```
Then we install a tool to easy upload to gthub pages:
```
pip install ghp-import
```
And use it to do so:
```
ghp-import -m "Generate Pelican site" --no-jekyll -b master output
```
This will create a commit on the master branch with the output content, all that with the right format for github pages.
We then push the changes of that master branch :
```
git push origin master
```
In the dev branch, add, commit and push your changes.

For future modification of your site : 
 - add/modify the content folder
 - update the output with `pelican content -o output -s publishconf.py`
 - create a commit and update the master branch with `ghp-import -m "Generate Pelican site" --no-jekyll -b master output`
 - and push theses changes `git push origin master`
 - you can also commit and push your changes of the dev branch

And that's it !