Markdown & Markdoc Guide

Published: 2/1/2026

What is Markdown?

Markdown is a lightweight markup language that lets you format text using simple, readable syntax. It's widely used for documentation, blog posts, and README files because it's easy to write and read.

What is Markdoc?

Markdoc is an extension of Markdown used in Bloomfolio that allows you to use custom tags for rich media embeds (Spotify, YouTube, Twitter). Files using Markdoc components must have the .mdoc extension.

Quick Facts:

• Standard blog posts: .md extension
• Blog posts with media embeds: .mdoc extension
• Add components via Keystatic CMS (visual editor) or manual editing
• Components currently only available in blog collection

Markdown Syntax Guide

Headings

Create headings using # symbols. More # symbols mean smaller headings.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Best Practice: Use only one H1 per page (your title), and maintain proper heading hierarchy (don't skip levels).

Text Formatting

**Bold text** or __Bold text__
*Italic text* or _Italic text_
***Bold and italic*** or ___Bold and italic___
~~Strikethrough text~~
`Inline code`

Renders as:

• Bold text
• Italic text
• Bold and italic
• Strikethrough
• Inline code

Lists

Unordered Lists:

- Item 1
- Item 2
- Nested item 2.1
- Nested item 2.2
- Item 3

Ordered Lists:

1. First item
2. Second item
3. Third item
1. Nested item
2. Another nested item

Task Lists (GitHub-style):

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Links

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")
[Reference-style link][1]

[1]: https://example.com "Reference URL"

Internal Links (within your site):

[About Page](/about)
[Blog Post](/blog/my-post)
[Project](/projects/my-project)

Images


Best Practices:

• Always include descriptive alt text for accessibility
• Use relative paths for local images (./image.png)
• Optimize images before adding (aim for < 1MB)
• Use meaningful filenames

Example:


Code Blocks

Inline Code: Use single backticks

Use `const` for variables that won't change.

Code Blocks: Use triple backticks with language specification

```javascript
function greet(name) {
return `Hello, ${name}!`;
}
console.log(greet("World"));
```

Supported Languages:

• javascript / js
• typescript / ts
• python
• bash / sh
• css
• html
• json
• yaml
• markdown / md
• And many more!

Code Block with Title:

```javascript title="greet.js"
function greet(name) {
return `Hello, ${name}!`;
}
```

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And have multiple paragraphs.

Renders as:

This is a blockquote. It can span multiple lines.

Nested Blockquotes:

> First level
>> Second level
>>> Third level

Horizontal Rules

Create dividers using three or more hyphens, asterisks, or underscores:

---
***
___

All render as a horizontal line.

Tables

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1 | Cell 2 | Cell 3 |
| Cell 4 | Cell 5 | Cell 6 |

Alignment:

| Left aligned | Center aligned | Right aligned |
|:-------------|:--------------:|--------------:|
| Left | Center | Right |

Markdoc Features

Markdoc allows you to use custom tags within your markdown files for rich media embeds and interactive components.

File Extension Requirements

⚠️ Important: Media components (Spotify, YouTube, Twitter) only work in .mdoc files, not .md files.

• Use .md for standard blog posts
• Use .mdoc for blog posts with media embeds
• Components are currently only available in the blog collection

Content Management Options

You can add Markdoc components in two ways:

Option 1: Keystatic CMS (Easier)

• Access the visual editor at http://localhost:4321/keystatic
• Click the "+" button in the content editor
• Select Spotify, YouTube, or Twitter component
• Paste the URL - Keystatic handles the rest
• Files are automatically saved as .mdoc

Option 2: Manual Editing

• Create/rename file with .mdoc extension
• Use {% %} tag syntax shown below

When to Use Markdoc Components vs Plain Markdown

Use plain Markdown (.md) when:

• Writing simple blog posts
• No need for interactive components
• Standard markdown is sufficient

Use Markdoc tags (.mdoc) when:

• Embedding media (Spotify, YouTube, Twitter)
• Creating interactive content
• Using custom components
• Need advanced formatting

Using Markdoc Tags

Markdoc tags are globally registered and don't require imports. Simply use the {% %} syntax in your .mdoc files:

---
title: "My Post"
description: "Post description"
publishDate: "2024-01-27"
---

# My Post Content

Regular markdown content here...

` `

Available Media Components

Bloomfolio includes three built-in media components for rich content:

Spotify Component

Embed Spotify tracks, albums, playlists, or podcasts:

{% Spotify url="https://open.spotify.com/track/..." /%}

YouTube Component

Embed YouTube videos using either ID or full URL:

{% YouTube id="video-id" /%} or {% YouTube url="https://youtube.com/watch?v=..." /%}

Twitter Component

Embed tweets using URL or ID:

{% Twitter url="https://x.com/user/status/..." /%} or {% Twitter id="tweet-id" username="username" /%}

Live Examples

Want to see these components in action? Check out the Rich Media Embeds Example page which demonstrates all three media components with live examples.

Writing Best Practices

1. Structure Your Content

Good Structure:

# Main Title

Introduction paragraph explaining what the post is about.

## First Section

Content for the first section...

### Subsection

More detailed information...

## Second Section

Content for the second section...

## Conclusion

Summary and next steps...

2. Use Meaningful Headings

Good:

• ## Installation Steps
• ## Common Errors and Solutions
• ## Performance Optimization

Avoid:

• ## Part 1
• ## More Information
• ## Details

3. Break Up Long Paragraphs

Keep paragraphs to 2-4 sentences for better readability:

Good:

Markdown is easy to learn. It uses simple, intuitive syntax that mirrors
how people naturally format text in emails.

The beauty of Markdown is its readability. Even in raw form, it's easy
to understand what the formatted output will look like.

Avoid:

Markdown is easy to learn and it uses simple, intuitive syntax that mirrors how people naturally format text in emails and the beauty of Markdown is its readability because even in raw form, it's easy to understand what the formatted output will look like and it makes writing documentation much faster.

4. Use Code Examples

When explaining technical concepts, include code examples:

## Using Array Methods

The `map()` method creates a new array:

```javascript
const numbers = [1, 2, 3, 4, 5];
const doubled = numbers.map(n => n * 2);
console.log(doubled); // [2, 4, 6, 8, 10]

### 5. Include Visual Breaks

Use horizontal rules, blockquotes, or images to break up long sections of text:

```markdown
## Long Topic

First part of the content...

---

Second part of the content...

> Important note: This is a key point to remember.

Final part of the content...

6. Link to Related Content

Help readers discover more:

For more information on setting up your portfolio, check out the
[Complete Guide](/blog/guides/bloomfolio-complete-guide).

Learn how to structure your content in the
[Content Collections Guide](/blog/guides/content-collections-guide).

SEO Best Practices

Write Good Meta Descriptions

Your frontmatter description is used for SEO:

---
description: "Learn Markdown syntax and MDX features in Bloomfolio with this comprehensive guide."
---

Tips:

• Keep under 160 characters
• Include primary keywords
• Make it compelling
• Describe what readers will learn

Use Descriptive Alt Text


Structure with Headings

Search engines use headings to understand content structure. Use them logically:

# Main Topic (H1 - only one per page)
## Major Section (H2)
### Subsection (H3)
#### Minor Point (H4)

Internal Linking

Link to other pages on your site:

Check out my [E-commerce project](/projects/ecommerce-platform) for a
practical example.

Accessibility Tips

1. Meaningful Link Text

Good:

Learn more about [Markdown syntax](https://example.com).

Avoid:

Learn more [here](https://example.com).

2. Image Alt Text

Describe the image content, not just what it is:

Good:


Avoid:


3. Heading Hierarchy

Don't skip heading levels:

Good:

# Title
## Section
### Subsection

Avoid:

# Title
### Subsection <!-- Skipped H2 -->

Common Mistakes to Avoid

1. Inconsistent Spacing

Markdown needs blank lines between elements:

Correct:

## Heading

Paragraph text here.

- List item 1
- List item 2

Incorrect:

## Heading
Paragraph text here.
- List item 1
- List item 2

2. Not Escaping Special Characters

If you need to display special characters literally, escape them with \:

\*This text has literal asterisks\*
\# This is not a heading

3. Mixing Markdown and HTML Unnecessarily

While you can use HTML in Markdown, it's better to use Markdown syntax when possible:

Prefer:

**Bold text**

Over:

<strong>Bold text</strong>

Markdown Cheat Sheet

Quick reference for common syntax:

# H1
## H2
### H3

**bold**
*italic*
~~strikethrough~~
`code`

- Bullet list
1. Numbered list

[Link](url)

> Blockquote

---

```code block```

| Table | Header |
|-------|--------|
| Cell | Cell |