Writing Posts In Markdown

Hello and welcome to the second post in my series on Building a Powerful Blog!🎉 Throughout this series, we'll be using Gatsby as the framework, GraphQL as the data layer, and Netlify as the CI/CD pipeline. We'll be covering everything you need to know to get your first blog site up and running, including a basic understanding of how Gatsby sites work, how to utilize the numerous Gatsby plugins, and incorporating GraphQL as your data layer. These solutions will help create a fully functional, streamlined, no-database solution for presenting your work to millions.

Today's topic will be on the use of Markdown for your blog posts. Before we get into it though, please know that I'm not saying Markdown is the best or only way you should be writing blog posts. Everyone should utilize what works best for them to get out there and start sharing your knowledge with your audience. You should build your brand in the most enjoyable and comfortable way for yourself. There are numerous ways to create and share your content with your audience, each with their own pros and cons, and Markdown is no different. While Markdown might not be that for you, I have found it to be the most intuitive and resilient way for writing blog posts. With that in mind, let's get into it with the following topics:

1. Why Markdown?
2. Formatting Your Content
3. Utilizing YAML Frontmatter
4. Adding Images and Video
5. Markdown Cheat Sheets

---

Why Markdown?

To answer this question, we first need to know what it actually is. Markdown is a lightweight markup language that you can utilize with plaintext documents to add formatting elements to. This is different than applications like Microsoft Word, where you click buttons to format your content and the changes are immediately visible. These are referred to as WYSIWYG (What You See Is What You Get) editors. With Markdown, you add various syntax to the text to specify the formatting for your content. This might be something like adding an asterisk before and after a phrase to make it italicized (i.e., *this is an italicized phrase*), or adding a number sign before it to turn it into a heading (i.e., # This Is A Heading). The goal of Markdown's syntax is to make it as readable as possible, without looking like it's been marked up with tags or formatting instructions.

Now that you have a little bit more background information on what Markdown is, let's get into why I decided to use it for my blog posts:

• Markdown is incredibly portable:
  • Markdown-formatted text can be creating and transferred between any device, running on any operating system. These files also can be opened by virtually any application. While word-processing applications allow you to save your work, they typically do so in a proprietary file format that can't be reopened in a different application.
  • Try taking a document created with Microsoft Word and opening it in Google Docs or Pages. You'll likely see many formatting changes that completely disrupts the flow of the document you spent days creating.
• The above also makes Markdown future-proof:
  • This becomes critical for important documents like dissertations, books, emails, technical documentation, and yes, blog posts on your website.
  • As Markdown can be used for everything, having a system that is future-proof ensures that your "everything" won't be lost because the application you're using stops working in the future.
• Markdown is everywhere:
  • It's supported in websites like GitHub, and numerous desktop and web-based applications. I've found these applications to be more intuitive and user-friendly than the standard word-processors currently on the market. Take Obsidian as an example. It's marketed as "A second brain, for you, forever" and that's exactly what it is.
    • This application uses connections between Markdown files to help create a mind map of your content.
    • It also is incredibly extensible so that you can make the app your own and has a vibrant community to help learn and create together.
    • Furthermore, you never have to worry about losing your content as everything sits in a local folder on your computer. Combine that with a cloud-based backup storage like Google Drive, and you have a perpetual mind-map that you can bring with you anywhere.

I hope at this point I've convinced you that using Markdown for your blog posts is the best way to go, or at least worth a try. If so, let's get into how I utilize it to create my blog posts!

---

Formatting Your Content

While Markdown syntax can be a bit nuanced and tricky to get used to, the best way to learn about it is to just begin using it. If you have Visual Studio Code installed on your computer, I would recommend beginning with that until you're a bit more comfortable with the language. To get started, open a new text file in VS Code by going to File -> New Text File (ctrl+n) and select Markdown as the language of the document. Go ahead and save your file, giving it whatever name you like, and selecting Markdown as the file type. You now have a playground to start learning Markdown with!

For our Markdown, we will be using the CommonMark specification, as it is already utilized by Visual Studio, GitHub, and Obsidian. We'll go through a couple of the main items here but I've included some links to Markdown Cheat Sheets at the end of this post to help further your knowledge on the syntax.

When it comes to starting your blog post, it's best to include a heading at the top, utilizing an h1 with a single number sign before it. For sub-headings further down in the article, you can create h2, h3, all the way to h6 headings with the relative amount of numbers signs before it.

Markdown	HTML	Rendered Output
# Heading One	<h1>Heading One</h1>	Heading One
## Heading Two	<h2>Heading Two</h2>	Heading Two
### Heading Three	<h3>Heading Three</h3>	Heading Three

With headings in place, you can add in a Table of Contents as well, which includes making an ordered list and linking to your headings. To make an ordered list, you start on a new line with a 1.. For each additional item needed in the ordered list, you just move to a new line and increment the value. The next part is to create the links to your headings, this involves using square brackets, [], to write the text the user will see, followed immediately by parenthesis, (), which is what will contain the link to the heading. For in-document links to any headings (h1 to h6), start with a number sign, immediately followed by a hyphen delimited string matching your heading in all lowercase. This would look something like #this-is-my-heading, which would link to # This is my Heading. Putting it all together, your Table of Contents would be created with the following:

                                                           

Markdown	HTML	Rendered Output
1. [First Heading](#first-heading) 2. [Second Heading](#second-heading) 3. [Final Heading](#final-heading)	<ol>   <li>     <a href="#first-heading">       First Heading     <a>   </li>   <li>     <a href="#second-heading">       Second Heading     <a>   </li>   <li>     <a href="#final-heading">       Final Heading     <a>   </li> </ol>	First Heading           Second Heading           Final Heading

With the headings and table of contents in place, you can start adding in the content; building out a blog post that everyone can enjoy and learn from. As stated earlier, there is a lot more syntax that can be utilized with Markdown to improve the formatting of your content so be sure to check out those cheat sheets. Let's continue forward though with how you can add metadata to your blog post, through the use of YAML Frontmatter!

---

Utilizing YAML Frontmatter

YAML frontmatter is utilized to capture the metadata about your blog post and is defined at the beginning of the file, starting and ending on lines with three dashes (---). This becomes incredibly useful to capture basic information including, but not limited to:

• Title
• Author
• Description/SubTitle
• Blog Series
• Date Created
• Date Edited
• Tags
• Banner Images

The list could go on and on, but you get the picture. Any general information about your post can be captured in key-value pairs, where the key is before the : and the value is after it. The best part about this is that it doesn't appear when the Markdown is rendered on your blog site, so you can put anything in there you need, pull it into your site with GraphQL, and use that data to add important UI elements. I'll get more into the details on how we can utilize this frontmatter in a future blog post though. For now, just know that the structure for your YAML Frontmatter should follow the below format, which has been taken directly from this blog post:

---
path: "/writing-posts-in-markdown"
dateCreated: 2022-10-18
dateEdited: 2022-10-18
title: "Writing Posts In Markdown"
description: "Struggling to find the best format for writing blog posts? Learn some quick tips and tricks to utilize the power of Markdown for your blog site."
series: "Building a Powerful Blog"
tags: ["tutorial", "beginners", "webdev", "markdown", "learning"]
banner: "./writing-posts-in-markdown-banner.png"
---

---

Adding Images and Video

Another area I wanted to mention is working with images and videos in Markdown. While adding images and gifs can be done using the Image syntax, adding videos has an additional layer of complexity to it. Trying to display videos in your Markdown content with the Image syntax will not work, as it doesn't support file types like MP4.

To add an image to your Markdown, utilize the following syntax:

![Alt text of the image](Absolute/Relative URL of the image)

An example of this would be:

![The beautiful views from Emory Peak at Big Bend National Park](./emory-peak-big-bend.png)

The rendered output would look like this:

Adding animations is a whole different story though. While great at grabbing people's attention and helping break up your content, animations in improper formats can greatly slow down the load time and responsiveness of your blog site. So, while you can use the GIF format with the Image syntax to display our animation, I would highly recommend against it. Instead, you'll want to use formats like MPEG4/WebM for animations and PNG/WebP for static images. This will help boost the performance of your site and improve the experience for your users.

The only problem is, the following won't work to display a video:

![This video will not properly show](https://media.giphy.com/media/lXu72d4iKwqek/giphy.mp4)

The rendered output would be:

As you can see, trying to use the proper format for animations causes issues when using the Image syntax in Markdown. What Markdown does support though is HTML elements. By adding the <video/> element, you can easily get the job done.

<video 
    autoplay 
    loop 
    muted 
    src="https://media.giphy.com/media/LpLd2NGvpaiys/giphy.mp4" 
    type="video/mp4" 
    controls="controls" 
    controlslist="nodownload nofullscreen noremoteplayback" 
    disablepictureinpicture 
    aria-label="Shocked Cosmo Kramer from Seinfeld">
    Sorry, your browser doesn't support embedded videos.
</video>

There's a lot to unpack here and but these specific attributes were selected after reading through the MDN web docs on the <video/> element. Some of these might not be applicable to you and your needs so I would recommend reading through those docs as well to identify what you would like to use. For example, if you're displaying a longer video, you might not want it to autoplay and loop back to the beginning on completion. You also might not want it to be muted so that the reader can listen to the video. If so, you just don't include those attributes with the element.

Depending on what you choose, the rendered output could look something like this:

As you can see, while videos add a bit of complexity to your blog post, it's not impossible to provide animations to your readers in a proper format. Utilizing the Image syntax for static images and the Video element for animations, you can better display your content to the reader, without hindering your site's performance.

---

Markdown Cheat Sheets

Hopefully by know, I've helped better explain the wonderful benefits of using Markdown for your blog posts and have helped clear up some of the more intimidating aspects. If not, that's alright as the community around Markdown is vast and there are numerous resources out there to help you learn more on the topic:

• Markdown Guide's Cheat Sheet: This is a great website to help learn more about Markdown and its basic and extended syntax.
• Adam Pritchard's Cheat Sheet: Another great resource for those specifically looking for syntax guidelines.
• Writing on GitHub: Perfect for those looking to write in Markdown primarily on GitHub.
• CommonMark Spec: For the daring adventurer looking to learn as much as they can about the specification utilized by VS Code and GitHub.

If you're struggling with any of the more detailed aspects about Markdown, the above resources should be able to answer all of your questions. If not though, please feel free to reach out and I'll do my best to help answer your questions!

---

There you have it! Those are the major components need to write and format your blog posts using Markdown, complete with metadata, properly formatted content, and eye-catching images and animations. All that's left is finding the content to write about. If you're struggling in this area, feel free to take a peak at some of my prior blog posts on my personal website for ideas and inspiration. You can also get a head start on building your skills by writing on what you are passionate about. Even if you feel like others won't care to read it, I promise you they are out there.

From here, we will continue on to using some of the plugins you installed while creating the site, alongside GraphQL, to build all the pages you need for your blog site using only templates. This is really where you can make the site your own, utilizing React and CSS to style the pages however you see fit. I hope you enjoyed this post and found it's content helpful as you continue your journey through web development! The links to my social media accounts can be found on the contact page of my website. Please feel free to share any of your own experiences with writing in Markdown, general questions and comments, or even other topics you would like me to write about. Thank you and I look forward to hearing from you!👋