I’m currently evaluating using Hugo (instead of Jekyll) for a documentation website for a few open source projects. Currently most of the documentation is within the repositories themselves on github. I’m trying to consolidate this the best I can under one website.
One issue I currently hit is URL rewriting relative links from markdown and/or asciidoc files from the code repositories themselves. Mostly everything would be feasible I think if I had the equivalent of
outfilesuffix from asciidoctor. So that I could strip the extension from the link as it is in the source file, when rendering the HTML for the page. More powerful rewriting rules for these relative URLs would be great, but I could probably change the location of things in github if need be.
Yet, keeping docs linking properly on github (as for latest dev stages) while having the docs render properly for actual end user consumption would be a great start…
What, if any, would be the best way to address this using Hugo? i.e. have a link like
[foo](../bar.md) render as
Check out Render Hooks You can write your own logic for markdown “rendered” links, images, headings etc…
So you can turn that markdown link into anything you want as HTML.
Great! That looks like it’d address part of the issue… i.e. Markdown, I’ll look into using that.
Do you know if the asciidoctor render used as some equivalent by any chance?
They are actually called Markdown Render Hooks and are only available with the Goldmark markdown renderer.
But maybe someone have had experience with Asciidoctor and found a hack/workaround…