What Docusaurus does with a Markdown file, and where an audio recording fits

Docusaurus takes Markdown through a file under the docs directory, with an identifier and a sidebar position in its front matter, and that is the door this page is about. The question worth asking is what an audio recording looks like by the time it arrives, because Docusaurus never sees the recording itself. It sees whatever the conversion handed over, and nothing else.

Docusaurus treats the file as MDX, which means characters that are harmless in plain Markdown are not harmless here. What comes out of an audio recording here is the speech as punctuated paragraphs, cut where the speaker actually stopped, so the structure Docusaurus 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 an audio recording into Docusaurus

The conversion drops silence, room tone, and the stretches where nobody says anything at all before Docusaurus ever sees them, because none of it carries meaning into Docusaurus and all of it costs something. What it keeps is the part you would otherwise have retyped by hand.

• The words come through punctuated, which is most of the work, and Docusaurus receives it as structure rather than as something to infer.
• The breaks between turns of speech are kept, so a handover is visible, which is the part Docusaurus would otherwise have to reconstruct on its own.
• Figures said out loud are written as digits rather than spelled out, so nothing downstream of Docusaurus has to guess at it.

What Docusaurus never gets back from an audio recording

Every conversion costs something, and a page listing only the gains is a sales page. Here is what an audio recording gives up on the way to Docusaurus, stated plainly enough that you can decide against it.

• Tone, emphasis and hesitation are gone, and they often carried the meaning, and Docusaurus will not get it back from anywhere.
• Speaker names are not attached, because nothing in the audio declares them, so nothing you build in Docusaurus should depend on it.
• The recording itself is not kept, so the transcript is all there is afterwards, which is a real cost inside Docusaurus and not a rounding error.

The Audio to Markdown step behind this Docusaurus page was measured

Groq does the conversion, and it was proven end to end on 30 August 2026: a recording made for the occasion, never transcribed anywhere before, came back with its witness word and its figure, split into two turns of speech. 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 Docusaurus would have received.

A crowded room and a cheap microphone cost accuracy, and nothing in the output marks which words were guessed. Docusaurus 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 recording is Markdown, what to do inside Docusaurus

With the Markdown in hand, set the identifier and sidebar position before the first build, because changing an identifier later breaks every link to it. That is a Docusaurus habit rather than a conversion setting, and it is where most of the value of converting an audio recording in the first place actually lands.

The constraint worth knowing before you start: an unescaped angle bracket or curly brace stops the build with an error pointing at the wrong line. It bites the same way whether the Markdown came out of an audio recording or out of something else entirely, but it bites hardest on long documents, which is what an audio recording usually is.

What we will not pretend about Audio in Docusaurus

• Docusaurus will not escape the characters MDX chokes on for you, and converting an audio recording first does not change that in the slightest.
• a converted document full of angle brackets is exactly the input MDX handles worst, which is a Docusaurus behaviour rather than anything the recording conversion did.
• The conversion costs half a credit and the price is shown before the recording is sent, whether the Markdown ends up in Docusaurus or nowhere at all.