Writing with Markdown and Atom - Images

This pertains to general writing, blogging, and documentation and other such things. I am nostly focusing on documentation and blogging, which overflows into general writing. In Atom.io there are many markdown plugins and I have been going through them to see which ones I like the best and which ones I don’t like and which ones I find useful and what I don’t. You can find more reviews, ideas, suggestions, tips, tricks and ramblings about this in this in this category here. There are many things I love about writing in markdown, and especially writing in markdown in Atom.io, which I have covered previously. However, something in general is missing from all my writing and documentation, and that is images. Images are great to get the point across. Being mostly code based for a blog, and trying to keep my documentation simple and to the point, this is not always a good thing. But sometimes, I feel like I have tried the same thing 100 times, gotten the same result and expected something different. Othertimes, to push my documentation to the next level (possibly for training purposes) having a good image goes miles. Documenting with images in markdown helps.
Let me show you.

Atom.io Package(s)

image-view If you don’t have it already, there is a package in Atom.io called “image-view”. It is made by the Atom.io team, which is always a plus. Very simple and easy to use, and does just what it says, allows you to view an image in Atom. It doesn’t add much to the time load (using time-cop for atom), and comes in handy when you are looking for a quick view and don’t want to leave your favorite IDE like me.

markdown-img-paste This is by “cocoakekeyu”. I chose this initially and it works great. I only chose it initially because it was higher on the list than others at the time and came up quicker. This works very well and is basic. Copy any image (ctrl-c, Right Click-->Copy, Print Screen ) and then on any line in a Markdown file just do ctrl-shift-v. This will create a folder named assets if you don’t already have one in that files current folder. Then it will place the file there, with a naming of “markdown-img-paste-[yyyymmddHHMMSS].png” and it will insert the corresponding Markdown image tag there.
I use ctrl-v all the time right now, and I use Print Screen constantly. I also like to use a different slightly different folder structure and naming convention (especially for my documentation), but I can cope with this for now. I also don’t like the naming of the file, so those are all reasons why I might switch to another, but this works great. I see another one named “markdown-image-paste” that I am going to try and see if that is better. UPDATE: I tried this out, and basically it didn’t work. Not out of the box at the least, which is something I would half-expect. If its supposed to be something this simple and with that little documentation, I would expect it to work like that. I also had an issue with the “Find” area at the bottom of the page because of this package. I couldn’t do a simple Ctrl+V for anything in that area. It created the folder that I put in the settings sections, which I think might be by default the “assets” folder, which was nice. However, it did not enter any code into the document for the image markdown or place the image in the appropriate folder. I would hate to tell people to avoid some packages, but if it doesn’t work without more massaging and it causes other issues, its hard not to.

markdown-image-paste markdown-image-helper markdown-image-assistant …and others… They all pretty much do the same thing just with some small differences, and a couple are just forked repositories of others (possibly an abandoned one) to try to customize it to the developers liking.

paste-image-2
I want to look more into this as it says “HTML” also. So this could add/paste the appropriate html tag in an html document instead of the markdown tag (slightly different).

atom-image-resize Looks very useful to be able to resize images and see previews while doing that in the editor. I don’t want massive images all the time embedded on my blog or documentation.

image2react draw-on-image I want to try this, as you can draw on an image…very interesting. Personally I would also love to have a package that oculd also do some editing…but that is asking alot and the question is then “what kind of editing”. Honestly, just a simple “crop”, “color/draw/mark” on image, resize and maybe a rotate. Yet, I just showed a few that might be able to get the job done.

Folder Orginization

Standard practice is to keep the images in a separate subfolder to where the document is. May people will have something like the following…

->Root Folder [folder] —>Blog [folder] ——>Article1.md ——>Article2.md ——>Article3.md ——>Assets [folder] ———>image1.jpg ———>image2.jpg ———>image3.jpg

Notice the folder that the “articles” are written in has a subfolder named “assets”. In Markdown its common to call the folder for images “assets”. This can also contain other things besides images when you start to go crazy, but typically not the main content. Blogging and writing and documentation follows the same rules.
Often, people will have a subfolder named “img” or “images” instead of “assets”, and then a subfolder for “js” or something else if they need it.
Sometimes, people will have both, “img” or “images” folder and an “assets” subfolder.
And still, also very frequent, people will have the “assets” subfolder with a subfolder inside that for “images” or “img” and then another for “js” or whatever other stuff they may have. This is a common web structure as well as other programming environments, so people will sometimes carry what is familiar and logical to them over to this.
All of these are valid and good. Whatever keeps you organized. Most of the time, the only thing going into the “assets” folder will be images, so not having subfolders within the “assets” folder is just as fine as renaming it “images”.
However, you may also be at the mercy of the Atom package for image pasting. If the tool doesn’t give you an option and just defaults to the “assets” directory, but you want it in the “image” directory, then every time you will need to move it. Again, just the “assets” directory could be acceptable to you, as it is with most people, but that is something to be aware of.

Markdown tag

    ![alt text - this displays when hovered over the image](assets/image_name.png)

Simple enough. No variation between flavors either.
The exclaimation point ( ! ) defines the beginning of the tag, followed by square brackets ( [ ] ) and finally by regular parenthesis ( ( )). All without spaces and each item directly next to each other. This is the cast for most items in markdown, except for headers and lists, which confuse me sometimes.
The square brackets define the “alt-text”. Alt-text, for those that don’t know is the little pop-up text when your mouse hovers over an image for more than 2 seconds. No clicking, just hover. This can be see on websites typically. The square bracket also doesn’t need to have something in it, and is only useful if someone is viewing the document digitally in some kind of reader or previewer. If you print it or someone is viewing the source, then the alt-text is near worthless. The parenthesis is not optional, and is required and needs to be a valid path. This should match your folder structure, as previously pointed out, and the location of your file/image. You have images in your “assets” folder, then it should be there, if they are in your “img” folder, then that would be what is put in there.
Those with some web background will also notice that this can be a relative or absolute path. The example is a relative path. It doesn’t start with a “/”, but starts with “assets” as in the subfolder relative to the current file. If there was a “/”, then it would be looking for the file based on the root of project and not where the file is located. This can be complicated and is a bit more advanced.

I hope this helps someone. Cheers!