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:
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:
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!
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.
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:
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!
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:
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" ---
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
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.
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:
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 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!👋