Markdown & Markdoc Guide

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

![Alt text](./image.png)
![Image with title](./image.png "Image title")

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:

![A developer coding at a modern workspace with dual monitors](./workspace.jpg)

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

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

![A comparison chart showing Markdown syntax on the left and rendered HTML on the right](./markdown-vs-html.png)

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:

![Bar chart showing 50% improvement in page load times after optimization](./performance-chart.png)

Avoid:

![Chart](./performance-chart.png)

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)
![Image](url)

> Blockquote

---

```code block```

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

Tools & Resources

Editors

VS Code: Excellent Markdown support with preview
Typora: WYSIWYG Markdown editor
Obsidian: Note-taking with Markdown
MarkText: Free, open-source Markdown editor

VS Code Extensions

Markdown All in One: Shortcuts and preview
markdownlint: Linting and style checking
Markdown Preview Enhanced: Advanced preview features

Online Tools

StackEdit: Browser-based Markdown editor
Dillinger: Online Markdown editor with live preview
Markdown Guide: Comprehensive Markdown reference

Next Steps

Now that you understand Markdown and Markdoc:

Create Content: Start writing blog posts with your new skills
Try Keystatic CMS: Access the visual editor at /keystatic to easily add media embeds
Experiment with Markdoc: Try the embed examples in your own posts (remember to use .mdoc extension)
Check Content Guide: Review the Content Collections Guide for schema details
Read Complete Guide: See the Bloomfolio Complete Guide for full setup

Happy writing! 🌼

What is Markdown?

What is Markdoc?

Markdown Syntax Guide

Headings

Text Formatting

Lists

Links

Images

Code Blocks

Blockquotes

Horizontal Rules

Tables

Markdoc Features

File Extension Requirements

Content Management Options

When to Use Markdoc Components vs Plain Markdown

Using Markdoc Tags

Available Media Components

Spotify Component

YouTube Component

Twitter Component

Live Examples

Writing Best Practices

1. Structure Your Content

2. Use Meaningful Headings

3. Break Up Long Paragraphs

4. Use Code Examples

6. Link to Related Content

SEO Best Practices

Write Good Meta Descriptions

Use Descriptive Alt Text

Structure with Headings

Internal Linking

Accessibility Tips

1. Meaningful Link Text

2. Image Alt Text

3. Heading Hierarchy

Common Mistakes to Avoid

1. Inconsistent Spacing

2. Not Escaping Special Characters

3. Mixing Markdown and HTML Unnecessarily

Markdown Cheat Sheet

Tools & Resources

Editors

VS Code Extensions

Online Tools

Next Steps