DH_MKDOCS(1)

✨ DH_MKDOCS(1) ✨ — the dh_mkdocs page, bestie edition 💅

okay so you found yourself in section 1 of the manual, the Debhelper zone, staring at dh_mkdocs and wondering what it even does. don't worry, i got you 🫶

🌸 NAME 🌸

dh_mkdocs — she helps you package documentation that was generated by MkDocs. that's it, that's the job, and she eats every time 💖

---

🦋 SYNOPSIS 🦋

dh_mkdocs [debhelper options] [-Xitem] [-Tpackage | --theme-package package]

like, look at her. so compact. so iconic 👑

---

💜 DESCRIPTION 💜

dh_mkdocs is a helper program for packaging documentation generated by MkDocs. and ngl she does a lot of heavy lifting behind the scenes, so let's break it down:

• she replaces static files with symlinks to their packaged versions whenever that's possible. and if your package is using non-standard themes, that's when you pull out the --theme-package option, like so:

dh_mkdocs --theme-package mkdocs-bootstrap

heads up bestie: dh_mkdocs only symlinks non-empty files with identical content. no cap. empty files and files that differ? she's not touching those, periodt.

• for the standard mkdocs and readthedocs themes, she replaces references to the highlight.js library from the CDN with references to the packaged version of that library. so you're not loading random stuff off the internet at runtime, you're loading the version that actually ships with your package. slay 🌈
• she adds the needed dependencies to the ${mkdocs:Depends} substitution variable. and please, please, add this variable to the Depends: field of your documentation package, or the whole thing just does not work. i'm begging 🙏

and the actual cheat code: you can pass --with mkdocs to dh(1) and it will automatically call dh_mkdocs right after dh_installdocs. no manual invocation, no forgetting, just vibes 😌

---

🎀 OPTIONS 🎀

• -Xitem, --exclude item — excludes files that contain item anywhere in their filename from being symlinked or edited. like, "not this one, not today." 💀

this option can be specified multiple times, so stack 'em up if you've got multiple things to exclude.

• -Tpackage, --theme-package package — scans the specified additional package for files that can be used as symlink targets. this is the "hey, check over there too" move 👀

this option can also be specified multiple times. again: stack away.

---

🔥 SEE ALSO 🔥

• debhelper(7)
• dh(1)

this program is meant to be used together with debhelper. like, they're a package deal, an inseparable duo, the main character and her bestie 🫶

---

👑 AUTHOR 👑

Dmitry Shachnev <mitya57@debian.org> — thank you for your service, legend 🫡

---

and that's the whole page, bestie! this was the dh_mkdocs(1) manual, coming to you from the Debhelper source, dated 2025-03-16. go forth and package your docs, you're gonna do amazing 💖✨🎀