Hugo

About preference to not use shortcodes

Continuing the discussion from Rendering code blocks properly from .md files:

@mojoa It’s just my personal preference to not use shortcodes.

The source of content for my sites is in Org mode (https://orgmode.org). What Hugo does using shortcodes can already be done (mostly) using Org macros.

I call Org mode an “active” markup language… because it can be powered using Emacs-Lisp.

Markdown on the other hand is “passive”. To give smarts to Markdown, things like Hugo shortcodes are needed.

Once you start baking shortcodes in your Markdown content, that content stops becoming portable and cannot be rendered directly by other Markdown parsers.

For that reason, I avoid using the shortcodes.

3 Likes

How portable is Org-Mode?

1 Like

If you have Emacs on your system, you have Org mode. You don’t have to install any extra package.

If you don’t have Emacs installed, there’s a little chance that you are using Org mode (which is a bit sad).

But I see that Org parsers in various languages are getting developed (like the recent go-org), which allows non-Emacs users to also use Org mode (even if just as a passive markup language).


Also, just as Markdown files are parsed by default by GitHub and Gitlab, Org files get parsed too.

1 Like

As a person that uses nvim but occasionally tries to get into org-mode, both of those statements surprised me! Thanks. :slight_smile:

Well, as for that second statement, I am not surprised; I have seen even some Org mode users to be not aware of that :slight_smile:

To complete that second statement …

1 Like

My preference on .md is because it is simple. When handling content that is going to be ‘alive’ for a very long time i prefer the simple way to do it.

Why not mmark? What I 'm doing does not need all the features that mmark provides, I only need markdown basic syntax working well. Would be interesting to see if there is a global variable that makes hugo use mmark to render .md files without the need of front matter or .mmark extension. Or options to chose the markdown engine without front matter or changing extensions.

And, if the content need a very complicated structure, I’ll go for mmark and some post processing in the layout, but no shortcodes, not mixing content with no portable logic. If I need to use shortcodes, I drop it, and start again, but no shortcodes.

I am wondering if the non-portability feature needs to be mentioned in the Docs?
People learning Hugo may not be aware of this.
Are their any other possible ramifications to using shortcodes?

I believe that it’s made pretty obvious that “Hugo Shortcodes” is a Hugo feature.

People using Markdown should know the Markdown syntax IMO.

From the docs:

Hugo created shortcodes to circumvent these limitations.

1 Like

That’s why I use markdown with few HTML tags if really needed. That is portable, also to CommonMark and Goldmark.

For complex, repeating code on selected pages Hugo shortcodes are absolutely fantastic—but as you said: they are Hugo shortcodes.

Asciidoctor is a fascinating alternative and supports everything markdown lacks, but is not as widely spread.

My thoughts about this is that shortcodes is a workaround that I hope will go away:

  • we have a figure and ref/relref shortcode that we should try to make obsolete. We should be able to create configurable “markdown hooks” that will make it look OK on GitHub and even better in Hugo. It would probably be easier if CommonMark could agree some kind of element attribute syntax that Hugo could use.
  • Shortcodes would still serve a purpose for in-line scripting that I’m pretty sure will be out-of-scope for CommonMark, but we should probably find a way to hide the brackets for non-Hugo viewers.

@kaushalmodi is Org-Mode with Emacs-Lisp widely available outside of Emacs?

If my intention is to host documentation in Hugo, I prefer a Hugo-centric macro language that can access Hugo’s meta-knowledge of my site, leaving the content markup language to perform the same tasks that HTML does but with better readability. I try to limit my shortcodes to tasks that connect documents, especially if they’re outside /content.