Markdown: Simple way to write content

Markdown allows you to style text on the web. It enables you to format documents, apply bold or italic styling to text, insert images, and create lists, to name a few capabilities. Essentially, Markdown is regular text augmented with a few non-alphabetic characters, like # or -.

Your Handy Syntax Compass

Below is an overview of Markdown syntax usable in your .md files or any websites that support Markdown (e.g. Azure DevOps, GitHub, Reddit, StackOverflow, etc.).

Headers

# This is a h1 tag

## This is a h2 tag

#### This is a h4 tag

This is a h1 tag

This is a h2 tag

This is a h4 tag

Emphasis

Italicise with *asterisks* or _underscores_.

Bolden with **bold moves** or __bold plays__.

Mix it up with **bold and _italic_**.

Cross out mistakes with ~~oops~~.

Italicise with asterisks or underscores.

Bolden with bold moves or bold plays.

Mix it up with bold and italic.

Cross out mistakes with oops.

Code Blocks and 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' })
  }
}

Leveraging Custom Components

Enhance with NextJS-specific markdown:

<PostsNewsletterForm title="Like what you are reading?" />

Crafting Lists

Bulleted Lists

Assemble with ease:

- Coffee
- Tea
  - Green tea
  - Black tea

• Coffee
• Tea
  • Green tea
  • Black tea

Numbered Lists

Sequence matters:

1. Open up a file
1. Write markdown
1. Output
   1. Preview
   1. Make changes

1. Open up a file
2. Write markdown
3. Output
   1. Preview
   2. Make changes

Blockquotes

As Dwight D. Eisenhower said:

> Plans are nothing;
> planning is everything.

As Dwight D. Eisenhower said:

Plans are nothing; planning is everything.

Inline Code

For the nuanced hints:

Don't forget to `git commit` your changes!

Don't forget to git commit your changes!

Embedding Images

Picture it vividly:

![Burley Griffin](https://images.unsplash.com/photo-1528415187930-56a01a88be1a?q=80&w=2150&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D)
Format: ![Alt Text](url)

Footnotes

Here is a simple footnote[^1]. With some additional text after it.

[^1]: Footnote reference 1 is here.

Here is a simple footnote¹. With some additional text after it.

Creating Links

Connect the dots:

https://www.example.com - it's automatic!
[Example](https://www.example.com)

https://www.example.com - it's automatic! Example

Interactive Task Lists

Checklist your progress:

- [x] Mastered Markdown
- [ ] Conquer the world

Tabular Data

Organise your info:

| Ingredient        | Quantity         |
| ----------------- | ---------------- |
| Flour             | 1 cup            |
| Water             | 1 cup            |
| Yeast             | 1 tbsp           |

Strikethrough

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

import PageTitle from './PageTitle.js'
;<PageTitle> Using JSX components in MDX </PageTitle>

Using JSX components in MDX

The section is specific to this blog framework. The default configuration resolves all components relative to the components directory.

Note: Components which require external image loaders also require additional esbuild configuration. Components which are dependent on global application state on lifecycle like the Nextjs Link component would also not work with this setup as each mdx file is built independently. For such cases, it is better to use component substitution.

Table of contents component

the toc variable containing all the top level headings of the document is passed to the MDX file and can be styled accordingly. To make generating a table of contents (TOC) simple, you can use the existing TOCInline component.

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