- Published on
Blog crash course & Markdown cheatsheet
- Authors
- Name
- Roastmylistings
- @roastmylistings
Table of Contents
Basics
Creating a post
Adding an article to the blog is as simple as creating a Markdown (mdx file) in the data
directory. The file name is used as the slug for the article.
After you created the article, you should configure the frontmatter and then you're off to the races.
The frontmatter of the file is used to populate the article's metadata, such as title, summary or images. Let's look at some frontmatter examples.
Frontmatter
So what is frontmatter?
Frontmatter is a block of metadata at the top of a file that is used to populate the article's metadata. It is written in YAML format. Here's an example of frontmatter:
title: 'Blog post title'
summary: 'A short summary of the article'
date: '2021-01-12'
tags: ['next-js', 'tailwind', 'guide']
That's just the basics, but there are more fields available. Here's a full list of all the fields that can be used in the frontmatter:
title: 'Blog post title'
summary: 'A short summary of the article'
date: '2021-01-12'
tags: ['next-js', 'tailwind', 'guide']
# Optional fields
lastmod: '2021-02-01'
images: ['/static/images/backdrop-1.webp']
authors: ['default'] # more authors can be defined under data/authors
layout: 'PostLayout' # 3 layouts are available: PostLayout (default) or PostBanner or PostSimple
draft: false # Set to true to hide the article from the blog
Layouts
There are currently 3 post layouts available: PostLayout
, PostSimple
and PostBanner
.
PostLayout
is the default 2 column layout with meta and author information.PostSimple
is a simplified version ofPostLayout
PostBanner
features a banner image.
Introduction to MDX
Markdown and Mdx parsing is supported via unified
, and other remark and rehype packages. next-mdx-remote
allows us to parse .mdx
and .md
files in a more flexible manner without touching webpack.
GitHub flavored markdown is used. mdx-prism
provides syntax highlighting capabilities for code blocks. Here's a demo of how everything looks.
The following markdown cheatsheet is adapted from: https://guides.github.com/features/mastering-markdown/
What is Markdown?
Markdown is a way to style text on the web. You control the display of the document; formatting words as bold or italic, adding images, and creating lists are just a few of the things we can do with Markdown. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like #
or *
.
See the Syntax guide for a complete reference.
Nested Routes
The blog template supports posts in nested sub-folders. This helps in organisation and can be used to group posts of similar content e.g. a multi-part series. This post is itself an example of a nested route! It's located in the /data/nested-route
folder.
Table of Contents
The TOCInline
component can be dropped into any post to generate a table of contents.
For example, the TOC in this post was generated with the following code:
<TOCInline toc={props.toc} exclude="Overview" toHeading={2} />
You can customise the headings that are displayed by configuring the fromHeading
and toHeading
props, or exclude particular headings by passing a string or a string array to the exclude
prop. By default, all headings that are of depth 3 or smaller are indented. This can be configured by changing the indentDepth
property. A asDisclosure
prop can be used to render the TOC within an expandable disclosure element.
Here's the full TOC rendered in a disclosure element.
<TOCInline toc={props.toc} asDisclosure />
Table of Contents
How
Simplify create multiple folders inside the main /data
folder and add your .md
/.mdx
files to them. You can even create something like /data/nested-route/deeply-nested-route/my-post.md
Syntax guide
Here’s an overview of Markdown syntax that you can use anywhere on GitHub.com or in your own text files.
Headers
# This is a h1 tag
## This is a h2 tag
#### This is a h4 tag
Emphasis
_This text will be italic_
**This text will be bold**
_You **can** combine them_
This text will be italic
This text will be bold
You can combine them
Lists
Unordered
- Item 1
- Item 2
- Item 2a
- Item 2b
- Item 1
- Item 2
- Item 2a
- Item 2b
Ordered
1. Item 1
1. Item 2
1. Item 3
1. Item 3a
1. Item 3b
- Item 1
- Item 2
- Item 3
- Item 3a
- Item 3b
Images
![GitHub Logo](https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png)
Format: ![Alt Text](url)
Links
http://github.com - automatic!
[GitHub](http://github.com)
http://github.com - automatic! GitHub
Blockquotes
As Kanye West said:
> We're living the future so
> the present is our past.
As Kanye West said:
We're living the future so the present is our past.
Inline code
I think you should use an
`<addr>` element here instead.
I think you should use an <addr>
element here instead.
Syntax highlighting
Here’s an example of how you can use syntax highlighting with GitHub Flavored Markdown:
```js:fancyAlert.js
function fancyAlert(arg) {
if (arg) {
$.facebox({ div: '#foo' })
}
}
And here's how it looks - nicely colored with styled code titles!
function fancyAlert(arg) {
if (arg) {
$.facebox({ div: '#foo' })
}
}
Footnotes
Here is a simple footnote[^1]. With some additional text after it.
[^1]: My reference.
Here is a simple footnote1. With some additional text after it.
Task Lists
- [x] list syntax required (any unordered or ordered list supported)
- [x] this is a complete item
- [ ] this is an incomplete item
- list syntax required (any unordered or ordered list supported)
- this is a complete item
- this is an incomplete item
Tables
You can create tables by assembling a list of words and dividing them with hyphens -
(for the first row), and then separating each column with a pipe |
:
| First Header | Second Header |
| --------------------------- | ---------------------------- |
| Content from cell 1 | Content from cell 2 |
| Content in the first column | Content in the second column |
First Header | Second Header |
---|---|
Content from cell 1 | Content from cell 2 |
Content in the first column | Content in the second column |
Strikethrough
Any word wrapped with two tildes (like ~~this~~
) will appear crossed out.
Footnotes
My reference. ↩