Getting started with mkprof

mkprof is a companion tool for MkDocs Material that converts Jupyter notebooks into blog posts. This post walks you through getting set up from scratch.

Installation

Install mkprof with pip:

pip install mkprof

You'll also need mkdocs-material if you don't have it:

pip install mkdocs-material

Scaffold a new site

The mkprof init command creates a complete, working site:

mkprof init my-blog
cd my-blog

This writes:

my-blog/
  mkdocs.yml              ← MkDocs configuration
  hooks.py                ← nav injection + recent-posts hook
  .gitignore
  docs/
    index.md              ← home page with recent-posts placeholder
    tags.md               ← tags index
    authors.yml           ← author metadata (if you provided a name)
    stylesheets/
      extra.css           ← CSS stubs for figures, photos, tables, DataFrames, code blocks, theme palette
      blog_nav.js         ← keeps the Blog section open by default in the sidebar
    javascripts/
      mathjax.js          ← MathJax configuration
    blog/
      index.md
      posts/              ← put your notebooks here

The generated site includes a few opinionated defaults — posts listed in the sidebar, a river-of-news home page, MathJax, a dark/light palette toggle — that differ from a stock MkDocs Material site. See Design for the reasoning. Anything marked # Style: in mkdocs.yml or hooks.py is a stylistic choice you can remove in a minute; the rest is functional.

Add your first notebook

Create a Jupyter notebook in docs/blog/posts/ and add a raw metadata cell as the first cell:

title: My First Post
date: 2026-01-15
authors:
  - your-slug
tags:
  - hello world

Write the rest of your post in the remaining cells as normal.

If the metadata cell is missing or incomplete, mkprof will prompt you when you next run mkprof or mkprof serve. The authors field shows a selectable list drawn from docs/authors.yml, so you can tick the right names rather than typing slugs by hand. Multiple authors can be selected for a single post.

Convert and serve (local development)

Run mkprof from the project root:

mkprof serve

mkprof will:

1. Discover notebooks in docs/blog/posts/
2. Prompt you to fill in any missing metadata through an interactive dialog
3. Convert each notebook to a Markdown file
4. Start mkdocs serve so you can preview the site at http://127.0.0.1:8000

mkprof (no subcommand) does the same but asks whether to build or serve after conversion.

CI and automated builds

For CI pipelines, use mkprof convert instead. It is fully non-interactive: no TUI, no prompts — it logs to stdout and exits non-zero if any conversion fails. Notebooks without metadata are skipped with a warning rather than halting the build.

# GitHub Actions example
- run: mkprof convert && mkdocs build

Any notebook that was skipped due to missing metadata will simply be absent from the built site. Run mkprof locally to fill in the metadata and commit the updated notebook before the next CI run.

Assets

Images and other assets referenced from notebook markdown cells should be placed in docs/assets/. Reference them as assets/filename.ext in your notebook — mkprof rewrites the paths correctly regardless of where MkDocs publishes the post.

HTML <img> tags whose src points to a local asset are automatically converted to Markdown image syntax, which ensures MkDocs handles the path depth correctly for blog posts.