Override rendering functions

[md384]

Hi. Is there a way to override the rendering functions? For example, I'd like to render a link differently if it links to page on our domain vs one off-domain.

I was thinking to override the RenderVisitor inner class in HtmlRenderer but it has private access. Is there another way to do this?

[csauve]

We had a similar use case of needing to modify the rendering of certain tags. For example we wanted to avoid SEO impact of the user-provided texts on pages, so links get rel="nofollow" and headers get rendered as styled paragraphs.

I found that you can't override the rendering of built-in node types, and need to replace them with nodes extending CustomNode or CustomBlock for your CustomHtmlRenderer to get called. I implemented a visitor extending AbstractVisitor and overrode visit for the tags I wanted to render differently. For example (groovy):

    @Override
    void visit(Link link) {
      def replacement = new CustomLink()
      replacement.destination = link.destination
      replacement.title = link.title
      replacement.appendChild(link.firstChild)
      link.insertAfter(replacement)
      link.unlink()
    }

CustomLink is a CustomNode that can be rendered specially:

    @Override
    boolean render(Node node, HtmlWriter htmlWriter, Visitor visitor) {
      if (node instanceof CustomLink) {
        htmlWriter.tag("a", [
            "href": node.destination,
            "target": "_blank",
            "rel": "nofollow"
        ])
        visitChildren(node, visitor)
        htmlWriter.tag("/a")
        return true
      }
      return false
    }

    private static void visitChildren(Node node, Visitor visitor) {
      Node child = node.getFirstChild()
      while (child != null) {
        child.accept(visitor)
        child = child.getNext()
      }
    }

So the steps are:

1. Parse the markdown as normal
2. Run a visitor on the node tree that replaces the nodes you want rendered differently with custom node types
3. Implement a CustomHtmlRenderer for the render phase that outputs your custom nodes the way you want

Hope this helps!

[md384]

@csauve Thanks, that works great!

Could probably do with an easier way to handle this is the future though.

[csauve]

Agreed, it would be nice if the CustomHtmlRenderer implementations could be used for any arbitrary node type. The order in which they're added determines the precedence. The default built-in renderer would only kick in if no custom renderer returned true for handling the type.

@robinst, is this a misuse of the API and does there exist a simpler way to do this?

[robinst]

Thanks for jumping in, @csauve :). That's actually a cool workaround.

This area of the API requires some thinking on how to do right to satisfy all the use cases. The current form is a result of being conservative with regards to API surface while still allowing some limited extension points. #31 also ties into this a bit.

The idea of going through CustomHtmlRenderers first is nice and simple. What I'm worried about is that the longer that list gets, the more expensive it is (for each node, we might go through the whole list). A way to avoid that would be to make CustomHtmlRenderer have a method that returns the node types that it is interested in, which would turn it into a map lookup. Maybe for built-in node types, allowing the extension of RendererVisitor would be simpler? Input appreciated :).

[csauve]

For thought experiments, I can offer some of the use cases we have currently:

• 
  and

  ---

  rendered as
  and

  ---

  instead
• Headings rendered as styled paragraphs
• Autolink URLs, but "mailto:" links are replaced with text
• Length of generated HTML can be truncated by visiting Text nodes and counting total length. Once limit is exceeded, next nodes are pruned away up the tree to the root to preserve closing tags
• HTML is escaped using the builtin functionality
• Links receive target and rel attributes, we may also whitelist the domains allowed in the future
• Images, Code, FencedCodeBlock are all unlinked and replaced with Text
• SoftLineBreak replaced with HardLineBreak

commonmark-java hit the sweet spot for customizability, simplicity, and quality. Its strong point is the ability to use visitors to mutate the tree rather than only outputting HTML. The hurdle to learning it was the distinction between custom and builtin nodes; I was wondering why my CustomHtmlRenderer wasn't getting called at all. I would suggest making the internal renderer and custom renderers implementations of the same thing, and accepting that interface through your API as middleware so it's more obvious to API users how it works, for example:

def nodeTree = parser.parse(markdown)

nodeTree.visit(new MyTreeMutatingVisitor())
nodeTree.visit(new MyTruncatingVisitor(500))
//...etc

//renderers explicitly provided to a visitor so users see how it works
nodeTree.visit(new DefaultRenderingVisitor(myHtmlWriter, [
  new MyHtmlRenderer(/*config...*/), //these implement same interface
  new DefaultHTMLRenderer(/*config...*/) //could be extended
]))

Like you've said, performance becomes important the more renderer implementations you add. I think the approach of implementing a RendererMiddleWare.listHandledNodes() is a good one.

More food for thought: there is the concern that any CustomHtmlRenderer can mutate the tree (e.g. node.unlink()) and then return false for handled. What's the behaviour for the next renderer that gets run? Maybe this problem goes away if listHandledNodes() implies no following middleware is called for the types returned.

[robinst]

@csauve: Quite a list you got there :). I think some of them should be done by modifying the node tree before rendering it.

So, thanks for your input. I now have a change that unifies CustomHtmlRenderer with the rendering of built-in nodes, see PR #49. It would be awesome if you could have a look and provide some feedback on it, feel free to comment.

[robinst]

Thanks for the comments, merged #49 now. Will be included in the next release soon.

[robinst]

Released in 0.5.0 now 🎉

[AnzhiZhang]

I would like to post my code which works for the new version to realize setting attributes in this example, for reference if anyone finds this issue when looking at these features #35 (comment)

HtmlRenderer
        .builder()
        .attributeProviderFactory(new LinkAttributeProvider())
        .build();

public class LinkAttributeProvider implements AttributeProviderFactory, AttributeProvider {
    @Override
    public AttributeProvider create(AttributeProviderContext attributeProviderContext) {
        return new LinkAttributeProvider();
    }

    @Override
    public void setAttributes(Node node, String tagName, Map<String, String> attributes) {
        if (node instanceof Link) {
            attributes.put("target", "_blank");
            attributes.put("rel", "noopener noreferrer nofollow");
        }
    }
}