Stripe如何使用Markdoc构建交互式文档

At Stripe, our product docs are designed to feel like an application rather than a traditional user manual. For example, we incorporate a user's own API test key into code samples, making it possible to copy and paste code that seamlessly works with the user's own account. We have client-side interactivity, like checklists and collapsible sections. We tailor the content to the individual user, conditionally displaying content based on their location or the Stripe features they use. These features result in a high-quality user experience that reduces friction and contributes to the success of developers.

在Stripe，我们的产品文档的设计旨在感觉像一个应用程序，而不是传统的用户手册。例如，我们将用户自己的API测试密钥合并到代码示例中，使得可以复制和粘贴与用户自己的账户无缝配合工作的代码。我们具有客户端交互性，如检查列表和可折叠的部分。我们根据个体用户进行内容定制，根据他们的位置或使用的Stripe功能有条件地显示内容。这些功能提供了高质量的用户体验，减少了摩擦，并有助于开发人员的成功。

For these capabilities to have the desired impact we have to make it easy for writers to use them in their content. Delivering a good user experience without compromising the authoring experience required us to develop an authoring format that enables writers to express interactivity and simple page logic without mixing code and content.

为了使这些功能产生预期的影响，我们必须让作者在其内容中轻松使用它们。在不损害创作体验的前提下提供良好的用户体验，我们开发了一种创作格式，使作者能够表达交互性和简单的页面逻辑，而不会混合代码和内容。

Over several years, we learned how to balance interactivity, customization, and authoring productivity while undertaking a major overhaul of our documentation platform.

经过多年的实践，我们学会了如何在进行大规模文档平台改造的同时平衡交互性、定制性和创作效率。

Past is prologue

过去即序幕

To understand how we got here it's important to understand where we started. The legacy documentation platform that we replaced was a monolithic Ruby application built with ERB templates and Sinatra routing. The content freely mixed HTML, Markdown, Ruby, and ERB helper functions.

要理解我们是如何到达这里的，了解我们的起点是很重要的。我们替换的传统文档平台是一个使用ERB模板和Sinatra路由构建的单体Ruby应用程序。内容自由混合了HTML、Markdown、Ruby和ERB辅助函数。

Mixing code and content provided a natural way to programmatically tailor the docs to the developer, but it posed serious challenges to quality and maintainability when the body...