from Hacker News

Interactive Docs with Markdoc

by tomger on 9/14/22, 11:36 AM with 47 comments

  • by gouggoug on 9/16/22, 12:14 AM

    I've always loved Stripe's interactive documentation, wondered how they did it and hoped they'd open-source it. I totally missed the news that they did back in May.

    Now, it seems that 99% of documentation tooling advertised is Markdown based; and e-v-e-r-y time I see this on HN I wonder why AsciiDoc[0] isn't more prevalent than Markdown.

    AsciiDoc is older than Markdown and out of the box supports things that Markdown doesn't, which has led to a proliferation of Markdown flavors that remind me the web browser experience of the 2000s.

    It is Stripe's documentation that led me a few years back to look into replicating their documentation, particularly the interactive part of it. While I wasn't able to find any tool out there that did this out the box, that's how I found about AsciiDoc in the first place, and then Antora.

    This tool, Antora[1], is based on Asciidoc and allows you to create amazing documentation websites. A while back I experimented and wrote a PoC of a plugin for Antora that made my documentation interactive.

    I also believe that AsciiDoc is what O'Reilly authors use to write books (edit: it is one of 3 languages they [2]use: AsciiDoc, HTMLBook, or DocBook XML)

    I wish AsciiDoc was more commonly used.

    [0]: https://asciidoc.org/

    [1]: https://antora.org/

    [2]: https://docs.atlas.oreilly.com/index.html#what-is-atlas-DNIR...

  • by jph on 9/15/22, 8:37 PM

    Markdoc syntax and capability looks so much like MDX (https://mdxjs.com). Can anyone who's evaluated Markdoc and MDX 2 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.

    I'm aware of the Markdoc page about "Why not MDX?" which explains that Markdoc is deliberately less capable than MDX. But the page doesn't show how to do typical needs (IMHO) such as loops or substitutions. And for simple writing, compare with standard markdown annotated with tags/templates using Liquid or Jinja or similar?

  • by drx on 9/15/22, 10:20 PM

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

      Special shout out to:
 
  @marcioAlmada for providing us with the @markdoc GitHub org.
  @koomen for gifting us https://markdoc.dev.

  • by 0xbadcafebee on 9/16/22, 1:28 AM

    Yet another company-specific reinvention of a wheel from somebody with too much money and time on their hands, and will be abandoned after a few years.

    Documentation is information intended for humans to understand complex topics. Code is information intended for machines to understand complex topics. Code makes shitty documentation. Code is time-consuming, error-prone, nit-picky, and extremely verbose compared to the kinds of tools designed for humans: WISYWIG editors, buttons, windows, graphics, diagrams, audio, video.

    Developers today have grown up in a world where doing anything requires writing code. They literally do not understand how to solve problems without writing code. And have even fooled themselves into thinking that writing code is a superior way for humans to solve a problem than clicking a button. So rather than have robust tools that solve our problems, we now only make tools that require us to create our own customized tools to solve our problems. Forever making slapped-together jigs for every project, rather than just buying and using a premade tool.

    Confluence is what a documentation-creating solution should be. Not only does it have a WYSIWYG editor, it has custom plugins, rich content, and dynamic components, all of which can be added anywhere, immediately, with a live preview, with no training, no code, no syntax. Simply an interface for an average human to make a beautiful, useful document, quickly and easily.

    From their page: "I like Markdoc because it lets us still do anything we want with code in the docs without bogging down the content authoring experience. If we need some new component, designers and engineers can whip that up. So as a writer, I can work in the docs content and stay focused."

    You can do the same thing with Confluence. They just had Not-Invented-Here syndrome, and wanted to do something with their excess engineers.

  • by m_ke on 9/15/22, 8:04 PM

    Should probably mention mdx since it's a much better alternative that has been available for a while

  • by BerislavLopac on 9/16/22, 8:49 AM

    I've tried to implement documentation using Markdoc, but failed to understand what are the advantages that it brings over tools like mkdocs [0] and Material [1].

    [0] https://www.mkdocs.org/

    [1] https://squidfunk.github.io/mkdocs-material/

  • by russellbeattie on 9/15/22, 11:22 PM

    I've recently been using Markdown (to my utter chagrin) in order to update my resume and blog, and I'm just astounded by how much recreation of solved problems is going on in that space. I prefer JavaScript/Node so I've played with UnifiedJS (remark/rehype), MarkdownIt, MarkedJS, and others. It's honestly just absurd how over-engineered each project is.

    If all you're producing is HTML - which is 99% of what Markdown is used for - having to deal with a raw AST in order to modify a document is like deciding to use Assembly instead of Python. Sure, it could be more efficient if you really want to spend the time, but it's generally a step backwards in every way.

    I've personally decided that the only predictable, reliable and maintainable way to deal with Markdown is to extract the frontmatter, then convert the rest into bog-standard CommonMark HTML and then use JSDOM to do any additional manipulation. So instead of fighting with some wonky AST tree and APIs, I can use the DOM and standard web tools and code.

    Markdown parsers will let you pass through HTML tags. You can define any tag you want. There is no difference between:

        {% callout type="check" %}
    {% /callout %}
    and

        <callout type="check">
    </callout>
    And anyone who went through the XSL trend of the early 2000s should know the long-term pain caused by putting logic in your documents.

        <xsl:if test="price = 10">
    </xsl:if>
    Recreating this with {% if equals(1, 2) %} is just ignoring decades of lessons already learned.

    Honestly, Markdown needs to be killed with prejudice. So much wasted time and effort getting it to do what people need it to do.

  • by behnamoh on 9/15/22, 9:26 PM

    Interesting to see another post on HN frontpage about Stripe's "incompetent" review team, and then see this one.

  • by ammmir on 9/16/22, 4:34 AM

    The one thing from the Stripe docs I like is the embedded API key in all the code snippets, but this seems difficult to accomplish with Markdoc, especially if you're rendering the whole site to static HTML.

    For example:

      ```bash
  curl https://api.example.com/stuff \
    -u {% apiKey /%}: \
    -d "foo=bar"
  ```
    If the user is logged in, I want the {% apiKey /%} to be replaced with something. Do I use a transform, node, or tag to accomplish it? It seems easier to write:

      ```bash
  curl https://api.example.com/stuff \
    -u MY_API_KEY: \
    -d "foo=bar"
  ```
    And then have custom JavaScript that runs on the page that does a search-and-replace for the string MY_API_KEY with the user's API key (obtained async with API, etc.). The documentation on Markdoc needs work.

  • by atonse on 9/15/22, 8:48 PM

    We’re using markdown + liquid with custom liquid tags.

    This looks so similar to that.