In my *.md files I write relative links as [go to doc1](doc1.md).
This is how navigation works great in Markdown-Monster’s preview and on GitHub when clicking through files (it’s the GitHub recommended way to do it → Basic writing and formatting syntax - GitHub Docs).
So, as long Hugo is not involved all works fine, locally (MarkdownMonster) and remote (GitHub).
Issue
When generating my pages with HUGO those hyperlinks remain untouched and are still pointing to *.md files - which - obviously do not exist rather than being “translated” into *.html!
Question
What can I do that all above mentioned [go to doc1](doc1.md) links are converted into <a href="../doc1.html">go to doc1</a> link?
Context
It might be that I have not understood a Hugo core principle or that I have overlooked something in the docs or on this channel. However - I have spent 2 hours for an answer and was not able to find anything. So - should there be a trivial answer alreday, maybe we should put this more explicitly into the docs.
GoHugo links to .md files because you link to .md files. Don’t. Not sure about “Markdown-Monster” and “Github Docs” but both have nothing to do with GoHugo, so expecting that to work automatically in GoHugo is expected to fail.
There is no way to make these three things work together smoothly.
Believe me, your Doc-Page has been one of the first pages I have read and several time since. However, it does not help nor does it make sense to me nor to others betting on the Markdown standard to become pervasive.
Markdown is a standard that got so popular recently with the Git community boosting it - with GitHub at the forefront and with GitHub offering a simple way to go directly from Markdown to Website.
So when the common opinion here is that Markdown for Hugo must remain a Markdown-derivative that does not work at other places and does not even keep up with standards nor best practices about how hyperlinks are generally encoded in Markdown, then this is the way into isolation.
Typing {{< ref “document.md” >}} alone is a nightmare and programming a shortcut for it does not make it better, right? Who does this? seriously? Besides such pages do not "navigate in modern Markdown editors and will break on GitHub completely.
So - I am sure - someone here has a (better) solution.
In the worst case - has anyone here a hint about where in the Hugo Source Code I can hard-code such change ? I do not really want to code a pre-generator that converts all *.md into *.html - for performance reasons. So better do this in the optimized parallel running Hugo code. Further we have to be aware, that some hosting companies - such as Netlify - offer their own HUGO-Generators as part of their CI-lifecycles: Its ok to fix Hugo source-code for ME, but it does not help the community, when such modifications are not part of the Hugo standard.
Thank you very much for this. Works in MarkdownMonster, GitHub and Netlify!!
Just making sure that I have understood the magic here:
Am I correct that the only thing needed to make this happen is what you have in the layouts\_default\_markup folder?
It is NOT Netlify doing special conversions - right? And when yes, the same thing should run this way when conventionally hugo generating the content and uploading the /public folder to AWS etc. ?
Hi Daniel,
Thank you so much for this one. Together with bep’s example I have finally got the idea and I am confident that is issue is solved for me and I can move forward.
Thank you all so much.
When I am sure, I have got all the details and have some life examples on my own, I might come back and may suggest where we might improve the docs a little bit, so that this IMPORTANT piece can be found and will be understood by newcomers as well.
I mean, I am an IT guy - but I can image that a non-IT person might have some headaches to get this right. Don’t you think so?
Documentation is on my to-do list, but like most developers it’s perhaps not as high priority as it should be. I do think having this on the Hugo Docs site would be good as well, but I’m not sure the appropriate place for pointers like this. Perhaps @bep and @jmooring or other Docs team members have thoughts on this?
Sometimes better questions lead to better solutions:
To sum it all up the (philosophical) question that remains is the following:
When a generator converts filenames - in our case from *.md to *.html - why does it make sense to keep hyperlinks that are pointing to those files unchanged at all?
Wouldn’t it be more logical that when a filename is changed by the generator that all hyperlinks that are pointing to this file must be changed as well?
And when THIS would be the way to go: why not having it baked into the mainstream rather than programming hooks that might be difficult to handle for ordinary folks and further might impact the generator’s performance?
