
Awhile ago at work, I was tasked with coming up with a good system for building documentation that could be published to the web, the historical approaches had been exporting Word to PDF, or creating a wiki site. For reasons I won’t get into here, both of these options just weren’t going to fly. Another option was to use something like a CMS for documentation, maybe a lightweight WordPress installation and theme. But, recently my friend Sage built his new blog with Jekyll and I had already been thinking about static gen for awhile, so I was pretty much dead set on building a static docs site.
After much research using https://www.staticgen.com/ as my guide for available options, I settled on MkDocs. The general concept was I had to come up with a solution that would be easy to roll-out to some developers and some content editors that everyone could collaborate on, and of all the systems I tried out, I found MkDocs to be the best fit for this project.
So, this brings me to this posts title: How to align images in MarkDown… well, turns out that was a tricky subject. It came up a few weeks after I had already rolled out the MkDocs system and did a tutorial for about 10 other employees. I got the question, how can we center our images? There were a number of methods:
- Use HTML – simple and effective, just drop the markdown syntax and use HTML.
- But we wanted to keep it markdown for those using markdown editors, html would break preview.
- Wrap the markdown image in an html <p align=center> tag.
- This would have worked to some extent, the image would show in markdown preview just not aligned.
- But.. for some reason MkDocs was having sporadic issues with this syntax and some images would not parse into HTML.
- Add an extension. As it turns out, the python markdown extension “extra” include an extension – attr.list, which adds a style tag into markdown and it’s default – just needs to be added to the MkDocs.yml.
But before I found answer 3, I did a lot of googling and stack overflowing on this one and found this to be quite the debated topic.. and then I found a bit of an answer on StackOverflow that was close but not perfect.
I have found nice solution in pure Markdown with a little CSS3 hack 🙂
  
Follow CSS3 code float image on left or right, when image alt ends with
<
or>
.img[alt$=">"] { float:right; } img[alt$="<"] { float:left; } img[alt$="<>"] { display: block; max-width: 100%; height: auto; margin: auto; float: none!important; }
From: http://stackoverflow.com/a/39614958/2839538
But I felt that leveraging the ALT tag like this was in bad form. So I thought about it for a minute and added a twist on this that seems to work pretty elegantly, by leveraging the location hash.
My fix: First your markdown image code:
  
Note the added url hash #center. Now add this rule in CSS using CSS3 attribute selectors to select images with a certain path.
img[src*='#left'] { float: left; } img[src*='#right'] { float: right; } img[src*='#center'] { display: block; margin: auto; }
Works like a charm.. although I did end up adding attr.list extension – I thought this was a super cool CSS hack that might be able to help someone out someday.
Thx a lot it really helped.
This is really elegant! Works as a charm in bare-bones MarkDown (like the Grav flat file CMS)