Hugo Markdown

Hugo provides some convenient markdown extensions. Hugo supports GitHub styled task lists (TODO lists) for the Blackfriday renderer (md-files). See Blackfriday config for how to turn it off. Example: - a task list item - list syntax required - incomplete - x completed. Hugo Markdown Footnotes emitting JQuery exception. Embed Tableau in Markdown (Hugo Academic) Hot Network Questions Is the requirement to have any type of degree.

tl;dr summary: jump to the solution down below for aneat trick.

We have extensions to the Markdown syntax, e.g. PHP Markdown Extra, GitHub Flavored Markdown. Markdown has many dialects. GitHub-Flavored Markdown is widely used and is based upon CommonMark, effectively mooting the question of whether or not CommonMark is an ideal specification. CommonMark is complicated and hard to implement. Hugo-WebSlides is a theme for writing beautiful WebSlides presentations in markdown with Hugo. Features: Based on WebSlides.js; Create slides with Markdown. Assign classes to elements without html. Shortcodes for components. Future Implementation: More component shortcodes! Hugo-WebSlides rendition of original demos.

the problem

as i was porting one of my old pages to Hugo, iencountered and unexpected snag. the page contained an image which i wanted toappear on the page centered (< gasp > fancy that!). sounds like a16-character problem solved straight out of muscle memory, right? not quite.


the philosophical angle

Hugo html

the thing is, that Hugo is mainly - butnot only - geared towards writingcontent in extended fact, one of the major selling points of static blog/content generatorslike Jekyll and Hugo is their proclaimed ability tolet you “Blog Like a Hacker”1, not“blog like an underpaid web designer”. so falling back toHTML would be a cop-out, but unfortunately Markdown syntax itself has nomeans of positioning images. theLaw of Leaky Abstractionsrears its ugly head again…

the official Markdown philosophystance on the subject of formatting is… conflicted. it starts out with abang:

A Markdown-formatted document should be publishable as-is, as plain text,without looking like it’s been marked up with tags or formattinginstructions. […] Markdown’s formatting syntax only addresses issuesthat can be conveyed in plain text.

which i can totally relate to: while i’m writing and re-reading the contenti don’t want to constantly tear through swathes of machine-readablegobbledygook. but then this philosophy fizzles out with a whimper:

For any markup that is not covered by Markdown’s syntax, you simply use HTMLitself.

ending up with the exact opposite of the original intent. oh well, that’sphilosophy for you.

Hugo authors are acutely aware of the problem, and so Hugo does come with asolution of sorts: “shortcodes”(and {{ <figure> }} shortcode in particular). this is a powerful concept andi’ve seen people really go to town with it, even on the subject ofimages.

unfortunately, this approach has two drawbacks that i take issue with. forone thing, i’m not a web designer, nor do i plan to become one. for meHugo, and the content engines i’ve been using before it, is but a means to anend. being back to square one reading swathes of gobbledygook intended for adifferent kind of parser instead of reading my content is not much of animprovement.

the other drawback stems from the “content engines i’ve been using before”Hugo remark above. formats like Markdown, rST and Textile are fairlyubiquitous and many static blog engines support each. Hugo’s shortcodes, onthe other hand, are Hugo-specific and are apparently rooted fairly deep inGo’s standard text templating. if for some reason i’ll be compelled to moveto a new engine again, i’ll be facing the unappealing prospect of having tofix a whole bunch of posts. “vendor lock-in” might sound a little harsh, but ivalue my freedom.

now, don’t get me wrong - shortcodes seem like a pretty good solution for theHugo blog templates code, i.e. for the all the other stuff, but not forthe content i actually care about, and some of which i’ve been dragging aroundwith me for many years.

the solution

in the end, after some energetic googling i did cobble together somethingthat gets the job done with minimal markup and no extraneous tags in thecontent.

to be able to center images in a Hugo-based blog or float them left/right(read: align left/right with text wrapping around them ), add the followingto your CSS (typically under static/css/ on your side, or wherever thetheme you’re using keeps its own stylesheets if you’re hacking the theme CSSdirectly):

then, inside your Markdown content, pull in the images as follows:

Hugo Markdown Cheatsheet


which should result in them being positioned correspondingly:

so, we’re down to 7 characters of overhead to center an image, with nary a tagin sight - not too bad! i also suspect that this will work in some of theother Markdown based site generators (Jekyll?), though i gaven’t tested itanywhere else.

Hugo markdown html

Hugo Markdown Image

i encountered the idea for this hack (though not for the centering - that tooksome extra googling)over, thanks, stiobhart, it did prove to be a “handy tip for other folks”!

the rant

incidentally, it was about 20 years ago that Netscape 3.0 added support forthe upcoming HTML 3.2, centering imageson web pages became a solved problem, and <center>/align=center gotingrained in my muscle memory. having to waste time on looking for anysolution to this non-problem again, 20 years later, after moving my blog toHugo was a bit of a disappointment… but i’ll touch on the topic of Hugodocumentation some other time.

  1. i’ll bet Tom is still chuckling about that one… [return]
Hugo uses Go’s html/template and text/template libraries as the basis for the templating.Read More »
Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site.Read More »
Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific.Read More »
The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page).Read More »
Install Hugo on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine where the Go compiler tool chain can run.Read More »
Hugo’s CLI scaffolds a project directory structure and then takes that single directory and uses it as the input to create a complete website.Read More »

Hugo Static Site Generator

How to handle Markdown and other markup related configuration.Read More »

Hugo Markdown

Hugo ships with an internal Disqus template, but this isn’t the only commenting system that will work with your new Hugo website.Read More »