Markdown is one of the main reasons I write today. It is what's known as an LML; a lightweight markup language, which allows you to simply write in plain text, and use simple syntax structures with symbols like asterisks (*) and brackets ([]) to represent common formatting options found in rich text. Be it bold, italicized, code or strikethrough text, as well as for headings, links, lists, images and even tables.
It is one of the best alternatives to the usual WYSIWYG (what you see is what you get) editors, that have that bar filled with buttons, each of which does a different thing, or even worse, some AI button asking you to press it to generate some slop for you.
If you are already a writer on the internet, have a website or have interacted with a Readme file on GitHub, you have already experienced Markdown, and are probably familiar with the ease of use Markdown provides. As it is the preferred format for writing in most static site generators and content management systems, used by plenty of there.
But if you are not familiar with Markdown... stop reading this article and go learn it! I encourage you to give it a go. It's incredibly easy and definitely worth your time. I make use of it for my website, to take notes, and literally everywhere with a text box that supports it. Markdown's sheer simplicity is just that convenient for me. It can really be a life-changer.
There are some fantastic programs out there, from robust note-taking/productivity tools like Joplin or Obsidian, with great communities around them building plugins and contributing to it; to super simple editors like ReText or [Typora] and apps like Markor on mobile.
I have to be honest, at first, this article was going to be a list of all the things Markdown cannot do. Not with bad intentions at all — Markdown deserves nothing but praise — but to showcase what is missing, and share some solutions to deal with those small issues. However, my brain ended up returning to the same thought:
Markdown isn't enough, and that's OK.
Markdown is functional and does its job well, and it accomplishes something that robust text editors can actively discourage sometimes. Just writing text.
To be fair, some will say the same happens when writing on a plain text file or a Markdown editor. However, in reality even if you have issues learning the syntax at first, with enough practice it becomes just part of the process, and most editors built with Markdown in mind will offer shortcuts and auto-completion for its syntax, while everything still is plain text in the background. It may take some time to get used to it, like with any new tool, but it's worth a try.
The entire point of Markdown is that it allows text to be written in a way that can be read by humans — when compared to something like HTML — and rendered/exported by the computer, to formats better suited for publishing to the web, or a magazine, like in this case!
Being able to have an skeleton that only contains the essentials that make a piece of writing into something understandable, is quite powerful. In a way, we are limiting ourselves, and that encourages us to nail down the basics for our articles or projects, and breed our creativity, for the better.
Not to mention, it is also a way to make your writing last for longer. It's just a text file with a fancy file extension.
With enough to ramble about, I have to accept that there are indeed some things that are missing from Markdown, but well, here's where the good old HTML, comes to the rescue, to make our writing, formatting, or accessibility better than Markdown alone.
What HTML does
With Markdown, some elements like classes and ids are out the window, everything is just what it is. This is perfectly fine when you are just writing, and maybe you don't even intend to convert the export the Markdown file to some other format.
However, when it comes to websites, classes are useful for many, many things, that let you express yourself and get creative with what HTML and CSS allow, such as galleries, buttons, comic panels and whatever else, the only limit is your imagination!
Rest assured, there are plenty of classless CSS themes and frameworks out there, that can end up rendering beautiful websites from simple Markdown files and folders. However, if you want something slightly more complicated in structure, anything using grids or flex elements that requires the use of the all-mighty <div>, Markdown will cut it short.
It should be noted, that some Markdown flavors from parsers such as Kramdown and Pandoc do allow the usage of classes and some other HTML attributes, but they are not the norm.
As a side note, Markdown has different flavors, and they are very similar but not completely equal. Some tools, like the already mentioned Obsidian, add extra syntax for unique functionality. As it is just plain text, most parsers and converters will support multiple flavors, but this is not granted. It is unfortunately one of the few negatives it has: it is not 100% standardized.
Images and accessibility
Yes, images are indeed supported in Markdown. However, they are very limited in most Markdown flavors. The format syntax is as follows:
Again, some flavors let you delimit some parameters such as image size and even classes, but not much more.
This works pretty well most of the time, however, it can be limiting, especially when it comes to accessibility. Adding alt text, a caption, and alternative media formats, is pretty much impossible without HTML.
Let's say we want to use images in .webp format are great to reduce the size of your pictures and load a page faster. All cool! But if you want to be able to view them from an old device or browser, it'll be rough.
Here's were HTML elements such as <source>, <picture>, <figure> and <figcaption> can come into play. Here's an HTML example. Depending on your static site generator, you can create a code snippet to have this handy when you need it.
<figure>
<picture>
<source srcset="/path/to/image.jpg" type="image/jpeg">
<source srcset="/path/to/image.png" type="image/png">
<img src="/path/to/image.webp" alt="alt text" title="image title">
</picture>
<figcaption>caption text</figcaption>
</figure>
To put it simply, this will let you source multiple files and let the browser pick the one it supports for certain media.
Similar things can be done with multiple types of embedded media, which we may want to add to our websites.
Microformats
The Indie Web is growing day after day! And some interesting protocols have showed up that allow for a better interoperability between websites. One example would be Webmentions, but that's a whole different beast that Markdown nor HTML alone can solve by themselves.
However, Microformats are a different initiative, they are "a set of simple, open data formats built upon existing and widely adopted standard". It's basically a standardized API that allows your web content to be interacted with in a cleaner way, and can be used by social web applications, search engines (such as Clew), aggregators, and other tools.
In the modern world, I guess this is a bit of a double-edged sword, as this does make it easier for bad actors to parse your website. However, most of them are just straight up fetching full websites and sitemaps without any sense of care for protocols, policies, the environment, server overhead, or anything.
There's a lot more
It is not difficult to find resources about Markdown and the different functionality it provides, and it is also not difficult to find how many things it cannot do.
The examples shared here are the most common that you might come across in a simple website dedicated to just writing. There are plenty others were Markdown might not be the right tool.
However, not all is lost. There are actually plenty of other markup languages that let you avoid writing raw HTML, while at the same time providing you with just as much functionality, while still ending up with a fairly readable and portable plain text file in the end.
One of them, which can probably end up as nightmare-inducing as HTML, is LaTeX. But there are also a couple of alternatives you can learn, such as AsciiDoc, reStructuredText and Org-mode.
Some are more feature-complete than Markdown while still remaining simple to use, but there's a reason none of them have managed to become as widely use by bloggers, writers and anyone in between.
So, go ahead and give it a try! it may as well just what you needed to begin your blogging journey, what gets you to write and share your work to the world, it may be just enough.
Joel (a.k.a joelchrono) started writing in 2021, when he discovered the Fediverse and the blogging world while stuck at home. He's a collector of hobbies, a technology and videogame enjoyer, and often reads science fiction or manga while procrastinating on more important things.
Member comments