Interactive Docs with Markdoc

This page summarizes the projects mentioned and recommended in the original post on news.ycombinator.com

Our great sponsors
  • Sonar - Write Clean JavaScript Code. Always.
  • InfluxDB - Build time-series-based applications quickly and at scale.
  • Scout APM - Truly a developer’s best friend
  • Zigi - Workflow assistant built for devs & their teams
  • markdoc

    A powerful, flexible, Markdown-based authoring framework.

    Really cool of @koomen to donate the domain, from the github repo (https://github.com/markdoc/markdoc):

    > Special shout out to:

  • mdx

    Markdown for the component era

    Markdoc syntax and capability looks so much like MDX (https://mdxjs.com). Can anyone who's evaluated Markdoc and MDX comment?

    I'm currently doing an architecture decision record about Markdown documentation, and will add Markdoc to the candidates. The leaders so far are MDX 2 with plugins for JSX-style work, and Svelte for a fully dynamic site.

  • Sonar

    Write Clean JavaScript Code. Always.. Sonar helps you commit clean code every time. With over 300 unique rules to find JavaScript bugs, code smells & vulnerabilities, Sonar finds the issues while you focus on the work.

  • MkDocs

    Project documentation with Markdown.

  • mkdocs-material

    Documentation that simply works

  • nate.io

    My website

    Your first example is essentially how it works on the Stripe docs platform. However, it requires a couple of custom components, including a CodeBlock component that renders code within code fences, and a component which understands how to display the user's API key. These are both very Stripe-specific, so it doesn't make sense to open source them.

    If you render the site to static HTML, though, you will have to do something more like a last-minute search-and-replace. Instead of rendering raw HTML, you could render the entire site to either the Markdoc AST or Markdoc renderable tree, which are both serializable. That's the approach that I use on my personal site [0], which implements a system similar to ContentLayer. [1]

    [0] https://github.com/nkohari/nate.io/blob/master/build/Content...

    [1] https://www.contentlayer.dev/

  • contentlayer

    Contentlayer turns your content into data - making it super easy to import MD(X) and CMS content in your app

    Your first example is essentially how it works on the Stripe docs platform. However, it requires a couple of custom components, including a CodeBlock component that renders code within code fences, and a component which understands how to display the user's API key. These are both very Stripe-specific, so it doesn't make sense to open source them.

    If you render the site to static HTML, though, you will have to do something more like a last-minute search-and-replace. Instead of rendering raw HTML, you could render the entire site to either the Markdoc AST or Markdoc renderable tree, which are both serializable. That's the approach that I use on my personal site [0], which implements a system similar to ContentLayer. [1]

    [0] https://github.com/nkohari/nate.io/blob/master/build/Content...

    [1] https://www.contentlayer.dev/

NOTE: The number of mentions on this list indicates mentions on common posts plus user suggested alternatives. Hence, a higher number means a more popular project.

Suggest a related project

Related posts