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:

1. Use HTML – simple and effective, just drop the markdown syntax and use HTML.
   1. But we wanted to keep it markdown for those using markdown editors, html would break preview.
2. Wrap the markdown image in an html <p align=center> tag.
   1. This would have worked to some extent, the image would show in markdown preview just not aligned.
   2. But.. for some reason MkDocs was having sporadic issues with this syntax and some images would not parse into HTML.
3. 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 🙂

![image alt >](/image-right.jpg)
![image alt <](/image-left.jpg)
![image alt <>](/center-image.jpg)

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:

![my image](/img/myImage.jpg#left)
![my image](/img/myImage.jpg#right) 
![my image](/img/myImage.jpg#center)

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.