Blog crash course & Markdown cheatsheet

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 of PostLayout
• PostBanner features a banner image.

Read more about layouts and see examples here.

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.

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 />

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

1. Item 1
2. Item 2
3. Item 3
   1. Item 3a
   2. 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 footnote¹. 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 |

Strikethrough

Any word wrapped with two tildes (like ~~this~~) will appear crossed out.