---
title: MkDocs
author: Sorin Sbarnea
tags: presentation
type: slide
slideOptions:
theme: moon
transition: 'fade'
progress: true
slideNumber: true
---

# mkdocs path

Migrating DevTools projects
from Sphinx to MkDocs.

---

# The good

- Natively supported by RTD
- Best theme for documentation material-docs
- Very actively maintained
- Also commercial plans and features
- Python based
- Popular, mkdocs itself 16k stars and materialk theme 13k

---

# The bad

- Main project lacks leadership
- But it looks stable
- Lots of plugins
- Most under personal github accounts
- Community health
- mkdocstrings vs material-theme
- some from original mkdocs team left
- **monorepo** plugin by Spotify stuggle

---

# Interactions so far

- material theme - 🟢 very good
- mkdocstring - 🟢 very good
- mkdocs - 🟡 ok-ish
- monorepo plugin - 🟠 poor
- zero feedback from Spotify folks
- markdown-exec - 🟢
- other plugins... (TBD)

---

# Challanges

- Monorepo plugin (single site conslidation)
- Navigation with monorepo
- File inclusion
- Speed at scale (❓)
- Top right github links not pointing to project
- Search scalability?

---

# Ecosystem

- Our current theme has [~50 python deps](https://github.com/ansible/mkdocs-ansible/blob/main/.config/requirements.txt)
- [best-of-mkdocs](https://github.com/pawamoy/best-of-mkdocs)