Hacker News Reader

Comment by atonse | Hacker News Reader

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

This looks so similar to that.

Hey, I'm the creator of Markdoc and the author of that blog post.

The key advantage of using Markdoc instead of using Markdown with liquid or another string-based templating system that preprocess the content is that the tags and other custom syntax are a first-class part of the Markdoc format. The document parses to an AST and the individual tags can programmatically manipulate the content and document node hierarchy instead of just manipulating or outputting strings of text that are passed on to a Markdown processor.

You may have misunderstood the parent post? Custom Liquid tags use code that can do anything you want: programmatically manipulate content, read databases, invoke APIs, autogenerate examples, run tests, use git, etc.

No, Segphault literally addressed why Markdown with Liquid is not the same as Markdoc on a processing level. “Custom tags processed by [thing that is not Markdown]” != “Markdown superset that makes custom tags first-class entities”. Either your template processor is run before the Markdown processor and outputs Markdown, or it’s run after the Markdown processor and outputs HTML. Neither one is doing what Markdoc is doing. Markdoc parses to an AST; “Markdown + [other thing]” does not. The difference may be immaterial in some use cases, including yours, but it’s still a difference.

Yes you're right there are differences. What I'm seeing is Markdoc custom tags and Liquid custom tags can both do any programmatic effects, ASTs, etc.

Perhaps an example may be useful? Or do you have an example where Markdoc custom tags are especially different/better than Liquid custom tags?

Markdoc custom tag syntax:

    {% bold %}
    Lorem ipsum
    {% /bold %}

Liquid custom tag syntax:

    {% bold %}
    Lorem ipsum
    {% endbold %}

Markdoc custom tag code is like this in JavaScript:

    export const bold = {
       render: 'Bold'
       …
    };

    import \* as React from 'react';

    function Foo({ children }) {
       return (
         <b>{children}</b>
       );
    }

    return Markdoc.renderers.react(
        content, React, {
            components: {
                Bold: Bold
            }
        }
    );

Liquid custom tag code is like this in Ruby:

    class Bold < Liquid::Block

      def initialize(_tag_name, _content, parse_context)
        super
        # Do whatever you want here,
        # such as parsing to your favorite AST,
        # or calling a DB, or RPC, or API, etc.
      end

      def render(context)
        # Do whatever you want here,
        # such as processing your favorite AST,
        # or using the rend context vars, etc.
        "<b>" + super.strip + "</b>"
      end

    end

    Liquid::Template.register_tag("bold", Bold)
    print Liquid::Template.parse(File.read("my.txt")).render

Reply on news.ycombinator.com