Write Blog Articles In Markdown On The Polyglot Developer

As you may or may not know, The Polyglot Developer is happy to accept guest contributions from the developer community. To find out more, check out the article titled, Write Guest Articles on The Polyglot Developer Blog. With that said, I’ve been receiving a lot of questions regarding Markdown, the format in which these blog articles are crafted.

The Polyglot Developer uses Hugo which is similar to Jekyll in the sense that articles are written in Markdown and then built into HTML. Don’t worry, Markdown is not bad and you’ll see how much more convenient it is than writing in other formats.

We’re going to get a quick look at producing content in Markdown so it can be published on the web.

Markdown does have its own syntax, like any language, so we’re more or less going to see what each of the very few operators do in action.

Headers

Headers generally provide a way to call out sections in your text. The larger the header number, the smaller the subsection, or otherwise text size. Take the following three headers for example:

h1

h2

h3

The above output is generated by entering the following lines of Markdown:

# h1
## h2
### h3

You’ll notice that each header is controlled by the number of hash or pound symbols that you place in front of it.

General Typography

Often you’ll find yourself needing to change text to emphasize something. In the most common circumstances you’d want to bold, italicize, or define as code, some piece of text.

To bold a piece of text, you’d enter the following:

**bold**

Notice that we’ve included a term inside two sets of asterisk characters. You don’t need to spell out the word “bold”, just make use of the asterisks.

To italicize some text, you’d enter the following:

_italicize_

Notice that we are using a single underscore on each side of the text that we wish to italicize.

Finally, if we wish to indicate that something is code, but not a code block, we’d enter the following:

`code`

In the above example, any inline code that we wish to call out is wrapped in a set of back-tick characters.

There are a few other things that you can do in regards to general formatting of text. For example, let’s say that you want to quote someone. You’d want to do a block quote:

The Polyglot Developer is an amazing resource - Nic Raboy

To include a block quote, you’d do the following:

> The Polyglot Developer is an amazing resource - Nic Raboy

The greater than symbol will quote anything that comes after.

In HTML, there are different types of lists that can be used. For example, there are unordered lists denoted with a bullet and ordered lists that use numbers.

• Unordered Item 1
• Unordered Item 2

1. Ordered Item 1
2. Ordered Item 2

The above two lists can be created with the following Markdown:

* Unordered Item 1
* Unordered Item 2

1. Ordered Item 1
2. Ordered Item 2

Notice that single asterisk characters create a bulleted list while numbers an ordered list. To indent either list, just insert a tab character or four spaces and then another asterisk or number.

Code Blocks

On a programming blog like The Polyglot Developer, you’re going to be sharing a lot of code, most of which shouldn’t be inline within the article. Instead, you should use code blocks like the following:

function main() {
    console.log("Hello World");
}

The above code block can be added by including the following in your Markdown document:

```
function main() {
    console.log("Hello World");
}
```

Notice that we’ve used three back-ticks at the beginning and end of our block. Anything within these back-ticks will retain their formatting.

Links and Images

There are plenty of circumstances where you’d want to link back to somewhere as a reference. Plagiarism is bad so you should always give credit where credit is deserved.

To create a link to an external resource, you’d include the following:

[The Polyglot Developer](https://www.thepolyglotdeveloper.com)

Notice that the link text is in square brackets and the link location is in parenthesis. Displaying images are similar to what you’d do with links.

Take the following for example:

The following Markdown will show the above image:

![The Polyglot Developer](https://www.thepolyglotdeveloper.com/the-polyglot-developer.png "The Polyglot Developer")

In the above example we’re linking to an external image. If you’re including images relative to your project and not remote, include the relative path.

Custom Hugo Tags for The Polyglot Developer

There were a few things that I needed to be included on this blog that are not natively a part of Markdown. For this reason, I had to create a few custom tags in Hugo to make this possible.

Take for example, a YouTube video:

To make the above video possible, I entered the following into my Markdown document:

{{ < youtube id="2gOhV-i3QAk" class="youtube-video" > }}

The id is the value that you see in the URL of every YouTube video. The class is specific to The Polyglot Developer and must be the same for all videos submitted to this blog.

Similarly to YouTube, we can also take advantage of sharing slideshow presentations like the following:

The above slides are uploaded to SlideShare and were added like the following:

{{ < slideshare id="7SwEt6b9f2lDTH" > }}

The id value is that of the one provided for any particular SlideShare presentation.

Conclusion

You just saw some Markdown that can be used for writing blog articles on platforms like Hugo or Jekyll, or even more specific, The Polyglot Developer.

There isn’t a whole lot to Markdown, so you can probably pick it up in an hour. Most of my struggle came from trying to mix HTML and Markdown, something that shouldn’t be done. Go all in with Markdown and use only custom tags for your generator.

More information on Markdown can be found on Daring Fireball.

Nic Raboy

Nic Raboy is an advocate of modern web and mobile development technologies. He has experience in C#, JavaScript, Golang and a variety of frameworks such as Angular, NativeScript, and Unity. Nic writes about his development experiences related to making web and mobile development easier to understand.