For some reason I decided to upgrade my Pelican setup from version 3.6.3 to 3.7.0 this morning. Because of the changes introduced, this wasn’t as smooth as expected and I needed to make some changes to my theme and configuration files manually. As of today (8th of January 2017), I would not recommend upgrading to 3.7.0, since a lot of the plugins are not ported to the new release, most prominently the render_math plugin (Github issue #38) which provides \(\LaTeX\) support via the MathJax engine.

A lot of theses necessary changes will probably be incorporated into the code base within the next weeks, so you can just sit it out and wait for the maintainers to fix it. However, if you really need to upgrade now for some specific reason, maybe the following will help.

Changes to `pelicanconf.py`

The MD_EXTENSIONS setting is deprecated now and was replaced with a MARKDOWN dictionary. You’ll need to transform your MD_EXTENSIONS list to key-value pairs under the extension_configs key in the MARKDOWN dictionary. To give you an example, this is what my old Markdown config looked like:

MD_EXTENSIONS = ['fenced_code', 'codehilite(css_class=highlight, linenums=True)', 'toc', 'markdown.extensions.abbr', 'markdown.extensions.footnotes', 'markdown.extensions.tables', ]

And here is what it needs to look like for 3.7.0:

MARKDOWN = {
    'extension_configs' : {
        'markdown.extensions.codehilite' : {'css_class': 'highlight', 'linenums': True},
        'markdown.extensions.abbr' : {},
        'markdown.extensions.footnotes' : {},
        'markdown.extensions.tables' : {},
        'markdown.extensions.toc' : {},
        'markdown.extensions.fenced_code' : {}
    }
}

Note that we can just use an empty dictionary {} to load an extension with its default config.

JINJA_EXTENSIONS was removed and now resides as a list under the extensions key in the JINJA_ENVIRONMENT dictionary. Here is my old config:

JINJA_EXTENSIONS = ['jinja2.ext.i18n', 'jinja2.ext.with_', 'jinja2.ext.loopcontrols']

and this is what it needs to look like for 3.7.0

JINJA_ENVIRONMENT =  {
    'extensions': ['jinja2.ext.i18n', 'jinja2.ext.with_', 'jinja2.ext.loopcontrols']
}

This wasn’t particularly important for me, but starting from 3.7.0 RSS feeds will now default to using the summary instead of the full content. You can control this behavior with the RSS_FEED_SUMMARY_ONLY property.

Adjusting your theme

The PAGES context variable was removed in favor of pages, which also means that all occurrences of PAGES will need to be modified in pelican-themes (issue #437). You should go through your theme and find out if PAGES is used somewhere. A quick way to recursively search for this is to use grep, e.g. something like
```
grep -Hrn " PAGES" theme/
```
which will provide you with the filename and line number of all occurrences. I only had a couple of occurrences so I just edited them manually. If you have more, you might want to use something like dired-do-query-replace-regexp in Emacs which will find and replace all occurrences automatically (or interactively if you want) using a regex.

Backward compatibility

As mentioned before, many plugins do not support the new version so far. Consequently, some plugins will fail during the initialization when trying to access variables like MD_EXTENSIONS or JINJA_ENVIRONMENT. One way to overcome this is to keep the deprecated variables in pelicanconf.py until all plugins you use are ported. For backward compatibility, let’s just let both ways live side by side for now. Here is what it looks for me:

# Markdown extensions to use...

# The following line is deprecated for versions >= 3.7. However, I will leave this in here for backward compatibility for now (since some plugins have not been ported to 3.7.0).
MD_EXTENSIONS = ['fenced_code', 'codehilite(css_class=highlight, linenums=True)', 'toc', 'markdown.extensions.abbr', 'markdown.extensions.footnotes', 'markdown.extensions.tables', ]

# For Pelican version >= 3.7 you will need the following...
MARKDOWN = {
    'extension_configs' : {
    'markdown.extensions.codehilite' : {'css_class': 'highlight', 'linenums': True},
    'markdown.extensions.abbr' : {},
    'markdown.extensions.footnotes' : {},
    'markdown.extensions.tables' : {},
    'markdown.extensions.toc' : {},
    'markdown.extensions.fenced_code' : {}
    }
}

# Jinja2 extensions to use...

# The following line is deprecated for versions >= 3.7. However, I will leave this in here for backward compatibility for now (since some plugins have not been ported to 3.7.0).
JINJA_EXTENSIONS =['jinja2.ext.i18n', 'jinja2.ext.with_', 'jinja2.ext.loopcontrols']

# For Pelican version >= 3.7 you will need the following...
JINJA_ENVIRONMENT =  {
    'extensions': ['jinja2.ext.with_', 'jinja2.ext.loopcontrols']
}

Now, from time to time you should come back and remove (or comment out) lines 4 and 21, recompile your static site and check if some plugins still complain about missing MD_EXTENSIONS or missing JINJA_EXTENSIONS. If not, you should remove the respective lines from your configuration.

Further thoughts

I think it would be best for you to read all of the version’s changelog to account for necessary changes that might affect you which weren’t discussed in this post. It’s also great to discover new features of this release.
When upgrading a software package to the latest version one should choose a reasonable point of time. If you wait to long, you might miss out on shiny new features or even risk being affected by security vulnerabilities. However, if you upgrade right after the release you might have to manually port you configuration instead of benefiting from automatic porting scripts that might come with the software update later in time. Furthermore, sometimes you can avoid a lot of hassle by waiting until the newer version is well established in the community, giving package maintainers the time to adjust their packages (in this case: the plugins). Surely, at some point you will have to make the transition, but often there is no need to hurry.

Changes to pelicanconf.py

Adjusting your theme

Backward compatibility

Further thoughts

Changes to `pelicanconf.py`