Browsable Markdown files while on GitHub

feature
1

I have a GitHub repo with Markdown docs, currently linked among them using the filename.md format. I’d like to render the docs using Hugo, and I also have the requirement to keep them browsable via GitHub.

How can I write the links so that they work both on GitHub and in Hugo?

The first requirement means that they have to be in the filename.md format (I tried in a test repo to use just filename or filename.html to point to filename.md files, but only got 404s).

If I understand correctly, permalinks or shortcodes in Hugo are not useful, because they’re only used in templates and not in Markdown docs.

There would have to be some way to intercept link generation during the Markdown parsing and rendering, to convert the filename.md links into filename.html ones (given uglyurls = true). Any way to do that?

Or any other way to satisfy both requirements? Thanks.

2

If those md-files had had “front matter” they you would only need a template (or use the default).

Front matter is metadata in the header about the page used by Hugo to create titles, permalinks etc.

One could envision that Hugo could create some default metadata if not present, or fetch it from GitHub (creation date …?)… But that would need some thinking by some developer.

3

Some noise at the beginning of each file would be tolerable. What do you mean by only needing a template, though?

4

The template is the HTML wrapper around the content - and the content is the rendered Markdown.

See: http://gohugo.io/templates/views

So you would at least need a single.html template to render a given document type, but probably also a list template to … list it.

For an example of how this front matter looks in GitHub, see (GitHub renders this Yaml-data nicely):

5

So in the front matter for each file I could define the path for the rendered output to have the .md extension rather than the .html one, and links would work. Having HTML files with the .md files is slightly ugly, though.

Otherwise I guess I could define a template filter function that replaces all the “.md” strings into “.html” in the rendered output.

I’ll test both approaches later (Europe bedtime approaching :slight_smile: ) and see what happens. Thank you for the help!

6

I’ll suggest you test it out and see for yourself. The HTML is just for layout/formatting of the packaging – the content and the formatting of the content will always be the md files.

7

Ugh, no joy.

The path for each document can be set. but the output file extension will always be HTML. There’s talk about making it configurable at https://github.com/spf13/hugo/issues/320.

Also, I cannot see a way to add a custom template functions to the ones Hugo adds at https://github.com/spf13/hugo/blob/master/hugolib/template.go#L505.

Any further ideas?

8

The code to support 320 is already committed. Just need to add a configuration option for it.

Hugo is complied. The only way to add custom template functions is exactly how we do it in the file you referenced. If you need one, it needs to be in that file, you can’t dynamically add one at runtime because hugo isn’t developed in a dynamic language.

That said, we are happy to have users contributed more custom template functions. Over half of those functions were contributed by the community.

9

Great news! I’d still keep this as last resort, though: HTML files with .md extensions would be weird.

Yes, I know it all too well. My first instinct was “monkeypatch!”, then I recalled this is not Python. :wink:

I’ll gladly contribute one (tests, docs and all). Would a generic string replace facility be interesting?

10

If it’s interesting to you than I’m sure others would benefit from it.

11

The Docker documentation needs this kind of dual homed linking, so I’ve created a PR to add support for it - see https://github.com/spf13/hugo/pull/1398

12

Hi there. Did anybody solved this problem? being able to use ‘.md’ relative links that work on github and gitlab, and also get converted in hugo to ‘.html’ links?

thanks!