Skip to content

Installation

We've envisioned the plugin with zero configuration as it's quicker to develop and easier to use. If you'd like to change the default behaviour, please open an issue.

pip install mkdocs-newsletter

To enable this plugin, you need to declare it in your config file mkdocs.yml.

plugins:
  - git-revision-date-localized:
      type: timeago
  - autolinks
  - section-index
  - mkdocs-newsletter

We rely on:

To create the RSS feeds well we also need the next configuration:

site_url: https://substitute.with.your.site.url
markdown_extensions:
  - toc:
      baselevel: 2

Finally make sure that you have a nav section in your mkdocs.yml file with at least one entry, otherwise the plugin won't work.

MkDocs configuration enhancements

There are some MkDocs tweaks that can make the plugin work better:

It can be useful to let know the readers that you publish the changes through newsletters and RSS feeds, we can do that in the footer and the header.

This section is assuming you're using the Material theme. It may work on others but I haven't tested it

You can add the RSS icon to the Social links footer section that points to the newsletter landing page with the next snippet:

extra:
  social:
    - icon: fontawesome/solid/rss
      link: https://your.site/newsletter/0_newsletter_index/

You can select from fontawesome/solid/rss-square or fontawesome/solid/rss.

You can add an announce banner at the top telling your readers to subscribe to the RSS feed by extending the theme and overriding the announce block with something like:

Assuming that the override theme directory is theme:

File: mkdocs.yml

theme:
  name: material
  custom_dir: theme

File: theme/main.html

{% extends "base.html" %}

{% block announce %}
<a href="https://your.site/newsletter/0_newsletter_index">
    For updates subscribe to the  <strong>RSS feed</strong>
    <span class="rss icon">
    {% include ".icons/fontawesome/solid/rss.svg" %}
    </span>
</a>
{% endblock %}

Update the site automatically

It's useful to create a continuous integration pipeline to keep the site updated and automatically build the newsletters.

If you're using github, you can use the next configuration:

File: .github/workflows/update.yml 
---
name: github pages

on:
push:
    branches:
    - master
schedule:
    - cron: 11 08 * * *

jobs:
deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
        with:
        persist-credentials: false
        # Number of commits to fetch. 0 indicates all history.
        # Default: 1
        fetch-depth: 0

    - name: Setup Python
        # https://github.com/actions/virtual-environments/issues/1202
        # uses: actions/setup-python@v1
        # with:
        #   python-version: '3.8'
        uses: actions/setup-python@v2
        with:
        python-version: 3.8
        architecture: x64

    - name: Cache dependencies
        uses: actions/cache@v1
        with:
        path: ~/.cache/pip
        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
        restore-keys: |
            ${{ runner.os }}-pip-

    - name: Install dependencies
        run: pip install pip-tools

    - name: Update requirements
        run: make update

    - name: Make the site
        run: make build-docs

    - name: Commit files
        run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add requirements.txt
        git add docs/newsletter
        git diff-index --quiet HEAD \
            || git commit -m "chore: update dependency and publish newsletters"

    - name: Push changes
        uses: ad-m/github-push-action@master
        with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        branch: master

    - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
        deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
        publish_dir: ./site

It assumes that you have the next Makefile:

File: Makefile 
.PHONY: update
update:
    @echo "-------------------------"
    @echo "- Updating dependencies -"
    @echo "-------------------------"

    rm requirements.txt
    touch requirements.txt
    pip-compile -Ur requirements.in --allow-unsafe

    pip install -r requirements.txt

    @echo ""

.PHONY: build-docs
build-docs:
    @echo "--------------------------"
    @echo "- Building documentation -"
    @echo "--------------------------"

    mkdocs build

    @echo ""

If you don't want to see the newsletters in the result of the search, use the mkdocs-exclude-search plugin to exclude all articles under newsletter/.

To do so:

  1. Install the plugin with 
    pip install mkdocs-exclude-search
  2. Add the following configuration to your mkdocs.yml 
    plugins:
  - search
  - exclude-search:
      exclude:
        - newsletter/*

Note that newsletter/* excludes all markdown files within a directory and its children. The paths must be relative to the docs/ directory.