Another Markdown Story

Markdown. Why bother?

I never figured out the reason why to the above question, so I thought I'd give it a go and try and explain markdown and share my experiences and reasons for trying it out with, I have to say, some satisfaction.

What is Markdown?

Markdown is a lightweight markup language used to format text, which is easy to write and read. It allows you to organise content with simple markup rules to include various elements to help format your writing. You can use any simple text editor application that comes with your computer.

Markdown files have the .md or .markdown extension. It's most commonly used in README files, documentation, blogs post, even this article is written in markdown.

Lost already?

Lightweight markup...? What's that first of all. Let's get that one explained. Markup is not a programming language. The classic markup language is HTML, the language used to write website where tags like <h1> denote headers, p denote paragraphs, <i> means italics, stuff like that. Markdown uses a lightweight markup language of its own that uses tags, symbols and headings to format and present a final document. HTML is a heavyweight markup language. Are you following?

What makes up a piece of markdown text?

Let's have a look at a simple sentence.

The story of the jumping fox

The quick brown fox jumps over the lazy dog.

The title first, The story of the jumping fox. That is a heading. Any text that you want as a heading starts with a hash '#' One hash makes the text the biggest, the more hashes in front of the text makes the text smaller.

The word 'quick', which is in italics. Just put an asterix "" at the beginning and the end of the word or words you want to make italic*. Easy stuff this...

Now bold like 'jumps'. Even easier, just put two asterix's at the start of the word or words that you want to make bold. So the above sentence code is like this:

'### The story of the jumping fox'

The *quick* brown fox **jumps** over the *lazy* dog.

So easy. Once you get used to markdown writing, the codes for the formatting just become muscle memory. Here is a list of well used symbols, codes, tags, call them what you will.

• Heading 1: # Heading
• Heading 2: ## Heading
• Bold: **bold text** or __bold text__
• Italic: *italicised text* or italicised text_
• Blockquote: > blockquote
• Unordered List: - Item, * Item, or + Item
• Ordered List: 1. Item
• Link: [name of website](https://www.example.com)

This is just a simple list. You can create tables and add graphics to your document just by using codes and writing it all in a simple text editor. Hold on though.... All this stuff can be done with any word processor like Word, Pages, Only Office and so on, why would I bother with markdown?

Good question, but... Here is a list which might help you see it differently.

• No clutter, no distractions, no "layout fiddling.*"
• You just write your stuff, then go back and format it later. Write first, format later.
• Platform independent. You can use any OS you like, Windows, MAC or Linux. Any text editor will do.
• It's future proof. Because your text is in good old fashioned ASCII, any text editor on any OS can open your text files. There is no proprietary stuff going on like .docx, .pages, etc.
• Easy exporting for sharing as a PDF or a .docx if you really must.
• AI. The markdown structure is the prefered format for AI agents, if your into that kind of thing.

The above is just a few reasons that comes to mind straight away, there are probably many more depending on what kind of writing you are into. For me it's the ability to write distraction free, portability and the ability to export out when I'm done writing something.

How about the writing and "seeing what you don't get"...?

We are so used of writing using word processors like Word and Pages, just to name two. They clutter the workspace with ribbons and formatting icons that we end up spending more time fiddling about with the look of a document, what about the content?

You can use just a simple text editor that comes with your computer, write, format your text then export it out, leaving the original text file alone. There are many purpose made markdown editors available that can render your text to show you how it looks as you type... Whoa...! Render, whats that... The ability of the editor to show you what you final output will look like is called rendering. Different markdown editors have different markdown engines and not all have the full complement of markdown codes, so you may not get to see what you are typing. For example you have to switch on text ==highlighting== in some editors, while some don't have highlighting at all, so choose your preferred editor carefully. I use both a plain text editor or Typora. There are no distractions with any of them.

PS. The ability to highlight text in my websites editor application, the plugin for Bludit, that is a markdown editor, does not render the code ==for highlighting== oddly enough.

So that's my take on markdown. I knew it existed for a while, but I never thought of using it, didn't see the point of it especially if I can do what I need in Apple Pages. However after using markdown, I realised what a cluttered, owned, by Apple, distraction filled mess of a writing app it can be. Yes of course you can justify your text, your images and so on, but are you really saying what you need to say, which should be first and foremost?

Help or harm...?

Dj