We used it to build the Streamlit docs. I assumed this is how everyone was doing documentation: https://github.com/streamlit/docs
> The key difference is that MDX supports arbitrarily-complex JavaScript logic (think: docs as code) while Markdoc enforces a strict separation between code and content (think: docs as data).
> Markdoc uses a fully declarative approach to composition and flow control, where MDX relies on JavaScript and React. This means MDX affords users more power and flexibility, but at the cost of complexity–content can quickly become as complex as regular code, which can lead to maintainability complications or a more difficult authoring environment.
This doesn't make sense to me? React is also a "fully declarative approach to composition and flow control".
> content can quickly become as complex as regular code
Okay, but has that actually happened in practice?
MDX, which allows embedding JSX isn't fully declarative, since arbitrary imperative structures can be used in JS blocks in JSX.
Reasons we treat docs like code
Coders and writers have borrowed tools and techniques from each other for decades. When you look at the history of producing docs and code together, you see that tools were invented specifically to produce docs while coding.
For example, the JavaDoc tool has been available since the first Java release in 1999. Visualizing the code in HTML, providing accessible online docs, and updating the documentation with the code were all keys to its success.
I don't think you have to choose between "can be powerful" and "can be simple."
If you want to lock things down so no one EVER puts code in your docs, Markdoc looks great.
Before we built Markdoc, our documentation was powered by ERB (embedded Ruby templates). Having content mixed with arbitrary code made it incredibly hard to reason about either. Because Markdoc is a declarative language rather than imperative, there's no intermediate state to keep track of, making things easier to follow.
At Stripe, both engineers and tech writers contribute to documentation. Markdoc makes things easier for everyone by keeping the content separate from the code, while still making it possible to build more interactive experiences when you want to. (For example, our integration builder [0] is also powered by Markdoc.)
When we say treat the docs like code, we mean that you: * Store the doc source files in a version control system. * Build the doc artifacts automatically. * Ensure that a trusted set of reviewers meticulously review the docs. * Publish the artifacts without much human intervention.
Docs Like Code, Anne Gentle, p. 10
"There is a lot more to building a proper Docs as Code workflow. There are a couple books we recommend that you check out:
Docs Like Code - Anne Gentle
Modern Technical Writing - Andrew Etter
"