From Wordpress To MkDocs

This is a post on how I migrated my blog from Wordpress to Material for MkDocs

When I first started my blog I chose to use Wordpress. At the time the reasons that drove this decision were mainly technical: - I wanted to deploy to my own managed instance - I wanted to experiment with managing and maintaining both a web server and a DBMS on my own - Wordpress user interface for writing, editing and managing post is actually pretty good

However, throughout the years I realized that managing and supporting the infrastructure for running Wordpress is an overkill and I opted for a much simpler, but equally powerful solution.

And this is MkDocs and most specifically Material for MkDocs, which is an excellent product, to my opinion as poweful as Wordpress, with more modern features and less hassle.

The Material for MkDocs Documentation is excellent, and it has a plethora of plugins, which makes it really fun to work with it, creating a professional representation of either a blog, documentation, or an all purpose website.

Deploying Material for MkDocs To Custom Domain

As I am running my own server instance for hosting my blog, I wanted a way to automatically deploy the generated blog web site to my remote server.

This is already documented in Material for MkDocs, however the defined Github Action in my case looks like below (note I am leveraging an scp Github Action to publish the generated content to my remote server).

name: aws
on:
  push:
    branches:
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: ~/.cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material
      - run: mkdocs build
      - name: copy file via ssh key
        uses: appleboy/scp-action@master
        with:
         host: ${{ secrets.HOST }}
         username: ${{ secrets.USER }}
         port: ${{ secrets.PORT }}
         key: ${{ secrets.AWS_PEM }}
         source: "site"
         target: "/var/www/html"

Material for MkDocs is highly extensible, hence making it easy to embed the Google AdSense code snippet. Someone would have to: - extend the theme by adding the below to the mkdocs.yml

theme:
  name: material
  custom_dir: overrides

- create an overrides folder on the root of the project - Locate the base.html file from the Material for MkDocs Github repo and copy it inside the overrides directory - Add the Google AdSense code snippet somehwere between the <body></body> tags

From Wordpress To MkDocs

Deploying Material for MkDocs To Custom Domain

Material for MkDocs And Google AdSense