The Basics of Markdown: A Text-Based Markup Language

The purpose of this article is to introduce you to the basics of Markdown. This is not an all-inclusive list of markdown commands that are available, but rather is a preview of some of the more widely used markdown commands that users of markdown are accustomed to using in their everyday workflow.

The markdown editor that I will be using is Obsidian. Obsidian is more than a markdown editor, but it does use markdown for presenting text and images in the platform.

I want to start out with one of the most basic uses of markdown, which is that of Headers. In markdown, as in HTML–a Hypertext Markup Language protocol–there are 6 levels of Headers. These are H1, H2, H3, … , H6 tags. The H1 Header is the largest and H6 is the smallest font size for the Header representation. Typically, H1 is used for the Title Header and H2, … , H6 are set aside for subheaders. Rarely does anyone use anything below the H4 Header tag. Look at this in the figure below. In this figure, I’ve split vertically two panes in Obsidian where the left-most pane displays the Markdown code and the right-most pane shows the preview of the result.

The H1 Header is created by typing the “#” symbol or hash symbol followed by a space and the text you wish to display as a H1 or Title Header. In the example, I have simply typed Header 1 to the right, which is displayed in H1 (Title) font on the right-hand pane. To produce an H2 or Sub-Header, you need to type “##” two hash symbols followed by a space and the text. Take a look at the H1, … , H6 Headers which were produced using markdown in Obsidian.

The next markdown code that I want to show you is how to bold word(s) within a sentence. To accomplish this, you can simply type your sentence, then encapsulate the word(s) that you wish to bold by either left-clicking on the word(s), then typing “**” two asterisks, which will automatically encapsulate the highlighted word(s) and make them bold. The sentence I’ve typed is: “This is a markdown file.” I’ve highlighted the word “This”, then typed two asterisks which encapsulated this word as shown on the left, resulting in this word being bold as shown in the right preview pane.

If I retype the sentence and this time I bold the word “This” as described above and follow that up with highlighting the word “markdown” and then typing a single asterisk “*”, this causes that word to be encapsulated with the single asterisk, like so: “*markdown*” and gives that word an italicized appearance.

Another frequent use of markdown in presenting plain text is the blockquote. To achieve a blockquote, simply prefix the text to be block quoted using the “>” greater than symbol followed by a space. See the example below where I have placed the “>” symbol in front of the sentence, “This is a blockquote”.

Another familiar use of markdown is for the creation of ordered (or canonical) and unordered lists. In the line that follows the blockquote example on the left-hand side of the editor, I show how you can create an ordered list. To accomplish this, simply start typing a “1” followed by a space, then the item. Here I use “Item 1”, “Item 2”, … , “Item 4”. After creating “Item 1”, just hit the Enter key on the keyboard and the markdown editor will jump to the next entry for “Item 2” by iterating the number to “2.” Likewise, if you wish to create an unordered list, then all you need to do is to type a “-” followed by a space, then the items that you wish to list. See the example in the figure below where I make the ordered list into an unordered list.

The “Horizontal Rule” is created by typing 3 dashes “-“. There is no need to hit the Enter key to produce this rule. This places a solid line across the editor pane covering roughly 80% of the width of that pane. I’ve gone back and encapsulated the unordered list I showed you how to create in the preceding paragraph with two horizontal rules using this method. Check it out.

Below the Horizontal Rule example, I show how you can create a code block in markdown. To accomplish this, type ` a back-tick symbol (The key just to the left of the "1" on the keyboard in front of and following the code block. In the example, I typed some HTML code as an example and it is rendered as code in the Preview Pane. If, instead, you wish to expand the code block to multiple lines, then you will need to type three back-ticks in front of and following the expanded block of code. See the example in the figure below which shows the resulting code block.

Frequently Used Markdown Code

Moving on to other commands that you have available to you in markdown, let’s say that you want to be able to embed a hyperlink into text. This is easily accomplished by first encapsulating the [text] in brackets, then followed (no space) by typing the URL in parentheses, such as (https://datapioneer-network.org). This results in text that when clicked will open the Web browser and take you there. If, instead, you just want to have a word(s) point to a file in your filesystem, then place brackets around that text and place the (/path/to/the/file) in parentheses. And, finally, if you want to have markdown embed the location to an image instead of text, you can type the text which points to the image file in brackets and the (/path/to/the/image/file) in parentheses. Placing a ” ! “, also known as a bang symbol, in front of the markdown will force the image to be revealed as shown in the figure below.

Creating tables in markdown is a relatively easy thing to do as well. To begin the process, for a 3-column table, type 4 ” | “, or pipe symbols (which is the key just above the Enter key on the keyboard). Then, hit the Enter key to go to the next line in the markdown editor and repeat the process except type 3 ” – ” dashes between these | pipe symbols. Go back to the first row of the table and enter Column Header information between the | pipe symbols. Now, return to the third, fourth, and so on rows of the table and repeat the process except add data (textual or numerical) between the | pipe symbols as shown below. Look at the result in the right-hand Preview pane.

One can even use markdown to create a footnote and the footnote content. To create the footnote, type the sentence(s), and at the end of the sentence where the footnote is to be positioned in the paragraph, type [^1] which is a set of brackets enclosing the “^1” caret symbol followed by the number 1 (for the first footnote). Then, place a line between the first line you typed and the line where, in the example, you type the [^1]: followed by a colon, then the text that describes the content of the footnote. Make sure that you indent this line using the Tab key. See the example below:

Additional Markdown Commands

Another markdown code you can utilize in your text is the “~~” double tilde symbols surrounding one or more words that you wish to strikeout. In the example below, I have introduced another header and a sentence below it. Since “some more” is improper English and somewhat repetitive, I wish to strike out the word “some” but leave it in the example to indicate that it was purposely removed. To accomplish this, simply highlight the word “some” in the example, and then type the ~~ double tilde symbols which will encapsulate that word and render a “strikethrough” as shown below in the right Preview pane.

And, last but not least, I want to show how one can create checkboxes in markdown which represent a checklist that can then be updated by clicking in the checkbox in Preview mode to render the item completed. In the example below, I created a checkbox by typing “- [ ] ” a dash, followed by a space, then a left bracket, followed by another space, and the final right bracket. Then, a space is placed after the checkbox, and text is typed as desired. After creating the information on the first checkbox line, hit the Enter key and a new checkbox will be created. Simply type the text for the second line and repeat the process for successive lines containing checkboxes. I’ve clicked in the first checkbox which renders that item completed resulting in a line through the item and an “x” being shown in the left Editing pane.

Strikethrough and Checkboxes

If you want to learn more about markdown and the markdown code which I didn’t include in this article, then visit the Markdown Guide website. The basic syntax will be found here as well.

Print Friendly, PDF & Email

Leave a Reply

Your email address will not be published.