What MkDocs does with a Markdown file, and where a video fits
MkDocs takes Markdown through a file under the docs directory, listed in the navigation of the configuration file, and that is the door this page is about. The question worth asking is what a video looks like by the time it arrives, because MkDocs never sees the video itself. It sees whatever the conversion handed over, and nothing else.
MkDocs builds the left hand navigation from the configuration and the page contents list from the headings. What comes out of a video here is the spoken words as punctuated paragraphs, with the title of the source and the detected language on top, so the structure MkDocs is looking for is actually present instead of merely implied. That is the entire trick, and there is nothing clever underneath it.
What survives from a video into MkDocs
The conversion drops the timeline, the thumbnails, and everything that was shown on screen without ever being said before MkDocs ever sees them, because none of it carries meaning into MkDocs and all of it costs something. What it keeps is the part you would otherwise have retyped by hand.
- The spoken words come through punctuated and cut into paragraphs, not as one unbroken block, and MkDocs receives it as structure rather than as something to infer.
- The title of the source travels with the transcript, which is the part MkDocs would otherwise have to reconstruct on its own.
- The detected language is stated rather than assumed, so nothing downstream of MkDocs has to guess at it.
What MkDocs never gets back from a video
Every conversion costs something, and a page listing only the gains is a sales page. Here is what a video gives up on the way to MkDocs, stated plainly enough that you can decide against it.
- Everything shown and never said is gone, including the slides behind the speaker, and MkDocs will not get it back from anywhere.
- Speaker turns are not labelled, so a two person conversation reads as one voice, so nothing you build in MkDocs should depend on it.
- The timing goes once the paragraphs are joined, so nothing points back at a moment, which is a real cost inside MkDocs and not a rounding error.
The Video to Markdown step behind this MkDocs page was measured
Groq Whisper behind our own extraction machine does the conversion, and it was proven end to end on 30 August 2026: a source that had never been converted before came back with its title, its language and its spoken text, with the cache switched off so nothing was recycled. That is one run on one day and not an average, which is exactly why the date travels with the claim instead of being left out of it. The same output is what MkDocs would have received.
This is the most fragile family we run, at 45 percent failure over thirty days, because the platforms refuse extractors whenever they feel like it. MkDocs has no way of telling you any of that from the inside, so it gets said here instead, on the page that sent you there.
Once the video is Markdown, what to do inside MkDocs
With the Markdown in hand, add the page to the navigation in the same change that adds the file, or it is invisible. That is a MkDocs habit rather than a conversion setting, and it is where most of the value of converting a video in the first place actually lands.
The constraint worth knowing before you start: a page missing from the navigation is still built, but unreachable except by direct link. It bites the same way whether the Markdown came out of a video or out of something else entirely, but it bites hardest on long documents, which is what a video usually is.
What we will not pretend about Video in MkDocs
- MkDocs will not warn about a heading level that skips a rung, and converting a video first does not change that in the slightest.
- two top level headings in one file produce a contents list nobody can follow, which is a MkDocs behaviour rather than anything the video conversion did.
- The conversion costs half a credit and the price is shown before the video is sent, whether the Markdown ends up in MkDocs or nowhere at all.