Markdown Editor: Syntax Guide and Best Practices — Complete Guide

Markdown Basics — Headers, Emphasis, Lists, Links, Images, Blockquotes

Markdown was created by John Gruber and Aaron Swartz in 2004 with the goal that a Markdown-formatted document should be publishable as plain text, without looking like it has been marked up with tags or formatting instructions. The syntax maps closely to how people naturally format plain-text emails.

Headings

Headings are created with hash signs #. The number of hashes corresponds to the HTML heading level (h1 through h6). Always put a space between the hash and the text, and leave a blank line before a heading for maximum parser compatibility.

# H1 — Page Title (use only once per page for SEO)
## H2 — Major Section
### H3 — Subsection
#### H4 — Sub-subsection
##### H5 — Rarely used
###### H6 — Rarely used

# Alternative H1 with underline syntax
Heading 1
=========

## Alternative H2 with underline syntax
Heading 2
---------

Emphasis — Bold, Italic, Bold+Italic

**bold text**          → <strong>bold text</strong>
__also bold__          → <strong>also bold</strong>

*italic text*          → <em>italic text</em>
_also italic_          → <em>also italic</em>

***bold and italic***  → <strong><em>bold and italic</em></strong>
___bold and italic___  → <strong><em>bold and italic</em></strong>

~~strikethrough~~      → <del>strikethrough</del>  (GFM extension)

`inline code`          → <code>inline code</code>

Lists — Unordered, Ordered, Nested

# Unordered lists — use -, *, or + (be consistent)
- Item one
- Item two
  - Nested item (indent with 2 spaces)
  - Another nested item
    - Deeply nested (4 spaces)
- Item three

# Ordered lists — numbers auto-correct
1. First item
2. Second item
   1. Nested ordered (indent 3 spaces)
   2. Another nested
3. Third item

# Starting ordered list at a specific number
4. Fourth item (continues from where you left off)
5. Fifth item

# Mixed nesting
1. Ordered parent
   - Unordered child
   - Another child
2. Second ordered parent

Links, Images, and Blockquotes

# Inline links
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")

# Reference-style links (keeps prose readable)
[Link text][ref-id]
[Another link][ref-id]

[ref-id]: https://example.com "Optional title"

# Auto-links (GFM — bare URLs become clickable)
https://example.com
<email@example.com>

# Images (same as links but with leading !)
![Alt text](https://example.com/image.png)
![Alt text](./local-image.jpg "Image title")

# Blockquotes
> This is a blockquote paragraph.
> It can span multiple lines.
>
> A blank quoted line creates a new paragraph.
>
> > Nested blockquote (double >>)

# Horizontal rules — three or more hyphens, asterisks, or underscores
---
***
___

Code Blocks and Syntax Highlighting — Fenced Blocks, Language Tags

Code is one of the most important elements in technical Markdown. There are two types: inline code (wrapped in single backticks) and block code (wrapped in triple backticks or indented with four spaces). Fenced blocks with a language identifier enable syntax highlighting in most renderers.

Fenced Code Blocks with Language Identifiers

```javascript
// JavaScript example
const greet = (name) => `Hello, ${name}!`;
console.log(greet('World'));
```

```typescript
// TypeScript with interfaces
interface User {
  id: number;
  name: string;
  email?: string;
}

function getUser(id: number): Promise<User> {
  return fetch(`/api/users/${id}`).then(r => r.json());
}
```

```python
# Python example
def fibonacci(n: int) -> list[int]:
    a, b = 0, 1
    result = []
    while a < n:
        result.append(a)
        a, b = b, a + b
    return result
```

```bash
# Shell / Bash commands
npm install react-markdown remark-gfm
export NODE_ENV=production
./deploy.sh --force
```

Common Language Tags Reference

The diff language tag is particularly useful for documenting changes — lines prefixed with+ render in green and lines prefixed with - render in red, matching what developers expect from git diff output.

```diff
- const API_URL = 'http://localhost:3000';
+ const API_URL = process.env.NEXT_PUBLIC_API_URL;

  function fetchUser(id) {
-   return axios.get(`${API_URL}/user/${id}`);
+   return fetch(`${API_URL}/api/users/${id}`).then(r => r.json());
  }
```

Tables in Markdown — Pipe Syntax, Alignment, Complex Tables

Tables are a GFM extension and are not part of the original CommonMark specification. They use pipe characters | to separate columns. The second row must be a separator row of hyphens that defines column alignment.

Basic Table Syntax and Alignment

| Column 1     | Column 2     | Column 3     |
| ------------ | ------------ | ------------ |
| Cell A       | Cell B       | Cell C       |
| Cell D       | Cell E       | Cell F       |

# Column alignment using colons in the separator row
| Left-aligned | Center-aligned | Right-aligned |
| :----------- | :------------: | ------------: |
| Text         | Text           | Text          |
| Apple        | Banana         | Cherry        |

# Pipes on the outside are optional but recommended for readability
Name | Score | Grade
---- | ----- | -----
Alice | 95 | A
Bob | 82 | B
Carol | 78 | C+

# You can include inline formatting inside table cells
| Feature      | Status           | Notes              |
| ------------ | ---------------- | ------------------ |
| **Auth**     | ✅ Complete       | JWT + refresh      |
| *Payments*   | 🚧 In progress    | Stripe integration |
| Search       | ~~Planned~~       | Deprioritized      |

Complex Tables — HTML Fallback for Merged Cells

Markdown tables do not support rowspan or colspan. For complex tables requiring merged cells, fall back to raw HTML within your Markdown file. Most Markdown parsers allow inline HTML.

<!-- HTML table with merged cells inside a .md file -->
<table>
  <thead>
    <tr>
      <th rowspan="2">Name</th>
      <th colspan="2">Scores</th>
    </tr>
    <tr>
      <th>Math</th>
      <th>Science</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Alice</td>
      <td>95</td>
      <td>88</td>
    </tr>
    <tr>
      <td>Bob</td>
      <td>72</td>
      <td>91</td>
    </tr>
  </tbody>
</table>

<!-- You can also mix Markdown and HTML in most parsers -->
Some **Markdown** text, then:

<details>
  <summary>Click to expand a complex table</summary>

  | A | B |
  |---|---|
  | 1 | 2 |

</details>

Extended Markdown (GFM) — Task Lists, Strikethrough, Footnotes, Auto-links

GitHub Flavored Markdown (GFM) extends CommonMark with several highly useful features. These are now so widely adopted that they are supported by nearly every modern Markdown tool, not just GitHub.

Task Lists (Checkboxes)

# Task list syntax — use [ ] for unchecked, [x] for checked
## Sprint Tasks

- [x] Design database schema
- [x] Implement user authentication
- [ ] Build dashboard UI
- [ ] Write unit tests
- [ ] Deploy to staging

### Sub-tasks work too
- [ ] Feature: User profile
  - [x] Profile view page
  - [ ] Edit profile form
  - [ ] Avatar upload
- [ ] Feature: Notifications
  - [ ] Email notifications
  - [ ] Push notifications

On GitHub, checked task list items in issue descriptions and pull request bodies render as interactive checkboxes. The completion percentage is shown in the issue list view. In README files and other Markdown files, they render as visual checkboxes but are not interactive.

Strikethrough, Footnotes, and Auto-links

# Strikethrough (GFM)
~~This text is crossed out~~ — renders as <del>This text is crossed out</del>

The old price was ~~$99~~ now $49!

# Footnotes (supported by GitHub, Pandoc, many parsers)
Here is a claim that needs a citation.[^1]
And another statement.[^note]

[^1]: This is the footnote text. It renders at the bottom of the document.
[^note]: Footnotes can have arbitrary labels, not just numbers.

# Auto-links (GFM automatically linkifies bare URLs)
Visit https://viadreams.cc for developer tools.
Contact us at support@example.com

# Without GFM, you need angle brackets for auto-links:
<https://viadreams.cc>
<support@example.com>

# Disabling auto-linking — wrap in backticks
`https://this-wont-be-linked.com`

# Mention and issue references (GitHub-specific extensions)
Closes #123
Fixed by @username
Related to #456 and PR #789

JavaScript marked.js — npm install, parseInline, Custom Renderer, Sanitization

marked.js is the most widely used JavaScript Markdown parser with over 30 million weekly npm downloads. It is fast (designed to run in browser and Node.js), supports GFM by default, and offers a powerful renderer API for customization.

Installation and Basic Usage

# Install marked and DOMPurify (for sanitization)
npm install marked dompurify
npm install --save-dev @types/marked @types/dompurify

// Basic usage — parse full Markdown document
import { marked } from 'marked';
import DOMPurify from 'dompurify';

const markdown = '# Hello World

This is **bold** text.';

// Always sanitize output before inserting into the DOM!
const rawHtml = marked.parse(markdown) as string;
const safeHtml = DOMPurify.sanitize(rawHtml);

document.getElementById('output')!.innerHTML = safeHtml;

// parseInline — parse only inline elements (no block wrapping)
// Useful when you want bold/italic/code but NOT wrapping <p> tags
const inline = marked.parseInline('This is **bold** and `code`') as string;
// Returns: 'This is <strong>bold</strong> and <code>code</code>'
// (no wrapping <p> tag, unlike marked.parse())

// Async mode (required in some environments)
const html = await marked.parse(markdown, { async: true });

Custom Renderer — Add CSS Classes and Modify Output

import { marked, Renderer } from 'marked';

// Create custom renderer
const renderer = new Renderer();

// Add CSS classes to headings
renderer.heading = ({ text, depth }) => {
  const id = text.toLowerCase().replace(/[^\w]+/g, '-');
  return `<h${depth} id="${id}" class="blog-heading blog-h${depth}">${text}</h${depth}>\n`;
};

// Open external links in new tab, keep internal links normal
renderer.link = ({ href, title, text }) => {
  const isExternal = href && href.startsWith('http');
  const target = isExternal ? ' target="_blank" rel="noopener noreferrer"' : '';
  const titleAttr = title ? ` title="${title}"` : '';
  return `<a href="${href}"${titleAttr}${target}>${text}</a>`;
};

// Wrap tables in a scrollable container
renderer.table = ({ header, rows }) => {
  const tableContent = `<table>\n<thead>\n${header}</thead>\n<tbody>\n${rows}</tbody>\n</table>\n`;
  return `<div class="table-wrapper" style="overflow-x:auto">${tableContent}</div>`;
};

// Add language class to code blocks for highlight.js
renderer.code = ({ text, lang }) => {
  const language = lang || 'plaintext';
  return `<pre><code class="language-${language}">${text}</code></pre>\n`;
};

// Apply the custom renderer
marked.use({ renderer });

const html = marked.parse('# Hello\n\nSome [link](https://example.com) text.');

marked.js Configuration Options

import { marked } from 'marked';

// Global options
marked.setOptions({
  gfm: true,         // GitHub Flavored Markdown (default: true)
  breaks: false,     // Convert \n to <br> (default: false, like GFM)
  pedantic: false,   // Use original Markdown spec (default: false)
});

// Per-call options (marked v5+)
const html = marked.parse(input, {
  gfm: true,
  breaks: true,      // Treat single newlines as <br> (useful for chat)
});

// Using marked with highlight.js for syntax highlighting
import hljs from 'highlight.js';
import 'highlight.js/styles/github-dark.css';

marked.use({
  renderer: {
    code({ text, lang }) {
      const language = hljs.getLanguage(lang || '') ? lang : 'plaintext';
      const highlighted = hljs.highlight(text, { language: language! }).value;
      return `<pre><code class="hljs language-${language}">${highlighted}</code></pre>\n`;
    }
  }
});

React Markdown — npm install, remark-gfm, rehype-highlight, rehype-sanitize

react-markdown renders Markdown as a React component tree rather than an HTML string, making it the safest and most idiomatic choice for React applications. It is built on the unified/remark/rehype ecosystem and is highly extensible via plugins.

Installation and Basic Usage

npm install react-markdown
npm install remark-gfm                # GFM: tables, task lists, strikethrough
npm install rehype-highlight          # Syntax highlighting via highlight.js
npm install rehype-sanitize           # HTML sanitization
npm install rehype-slug               # Auto-generate heading IDs
npm install remark-toc                # Auto-generate table of contents

// Basic react-markdown usage
import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import rehypeHighlight from 'rehype-highlight';
import rehypeSanitize from 'rehype-sanitize';
import 'highlight.js/styles/github-dark.css';

const markdown = `
# Hello World

This has **bold**, *italic*, and \`inline code\`.

\`\`\`javascript
const x = 42;
\`\`\`

| Name | Age |
|------|-----|
| Alice | 30 |
`;

export function BlogPost({ content }: { content: string }) {
  return (
    <ReactMarkdown
      remarkPlugins={[remarkGfm]}
      rehypePlugins={[rehypeHighlight, rehypeSanitize]}
    >
      {content}
    </ReactMarkdown>
  );
}

Custom Components — Replace Markdown Elements with React Components

import ReactMarkdown from 'react-markdown';
import remarkGfm from 'remark-gfm';
import Image from 'next/image';
import Link from 'next/link';

export function RichMarkdown({ content }: { content: string }) {
  return (
    <ReactMarkdown
      remarkPlugins={[remarkGfm]}
      components={{
        // Replace <img> with Next.js Image for optimization
        img({ src, alt }) {
          return (
            <Image
              src={src || ''}
              alt={alt || ''}
              width={800}
              height={450}
              style={{ maxWidth: '100%', height: 'auto' }}
            />
          );
        },

        // Replace <a> with Next.js Link for internal links
        a({ href, children }) {
          const isInternal = href?.startsWith('/');
          if (isInternal) {
            return <Link href={href!}>{children}</Link>;
          }
          return (
            <a href={href} target="_blank" rel="noopener noreferrer">
              {children}
            </a>
          );
        },

        // Add Tailwind classes to headings (or inline styles)
        h1({ children }) {
          return (
            <h1 style={{ fontSize: '2rem', fontWeight: 800, marginTop: '2rem', marginBottom: '1rem', borderBottom: '2px solid #e2e8f0', paddingBottom: '0.5rem' }}>
              {children}
            </h1>
          );
        },

        // Wrap code blocks in a container with a copy button
        pre({ children }) {
          return (
            <div style={{ position: 'relative' }}>
              <pre style={{ background: '#1e293b', color: '#e2e8f0', padding: '1rem', borderRadius: '8px', overflow: 'auto' }}>
                {children}
              </pre>
            </div>
          );
        },

        // Style blockquotes
        blockquote({ children }) {
          return (
            <blockquote style={{ borderLeft: '4px solid #0ea5e9', paddingLeft: '1rem', color: '#64748b', fontStyle: 'italic', margin: '1rem 0' }}>
              {children}
            </blockquote>
          );
        },
      }}
    >
      {content}
    </ReactMarkdown>
  );
}

Python markdown Library — markdown.convert(), Extensions (toc, codehilite, tables)

Python's markdown package is the standard Markdown processor for Python applications. It supports a rich extension ecosystem and is used by projects like MkDocs, Pelican, and Django-based CMS systems.

Installation and Basic Conversion

pip install markdown
pip install Pygments    # Required for codehilite syntax highlighting

import markdown

# Basic conversion
md_text = """
# Hello World

This is **bold** and *italic*.

```python
def greet(name):
    return f"Hello, {name}!"
```
"""

html = markdown.markdown(md_text)
print(html)
# <h1>Hello World</h1>
# <p>This is <strong>bold</strong> and <em>italic</em>.</p>

# Converting files
with open('README.md', 'r', encoding='utf-8') as f:
    text = f.read()

html_output = markdown.markdown(text, extensions=['extra', 'toc', 'codehilite'])

with open('output.html', 'w', encoding='utf-8') as f:
    f.write(html_output)

# Reusing the Markdown instance (more efficient for multiple conversions)
md = markdown.Markdown(extensions=['extra', 'toc', 'codehilite'])

for article in articles:
    md.reset()  # Must reset between conversions!
    html = md.convert(article.body)

Python Markdown Extensions Reference

import markdown

# 'extra' is a bundle that includes: tables, footnotes, attr_list,
# def_list, abbr, fenced_code — use it instead of listing individually
html = markdown.markdown(text, extensions=['extra'])

# Table of Contents
md = markdown.Markdown(extensions=['toc'])
html = md.convert(text)
toc_html = md.toc          # Access the generated TOC HTML separately
toc_tokens = md.toc_tokens # Access as a nested list of dicts

# Syntax highlighting with codehilite (uses Pygments)
html = markdown.markdown(text, extensions=['codehilite', 'fenced_code'], extension_configs={
    'codehilite': {
        'css_class': 'highlight',  # CSS class for the wrapper div
        'linenums': False,          # Don't show line numbers
        'guess_lang': False,        # Don't auto-detect language
    }
})

# To use the highlighted styles, also generate and link the CSS:
# python -m pygments -S default -f html > pygments.css

# Full configuration example
extensions = [
    'extra',           # tables, footnotes, attr_list, fenced_code, etc.
    'toc',             # [TOC] placeholder in Markdown
    'codehilite',      # syntax highlighting
    'meta',            # YAML-like metadata at top of document
    'nl2br',           # treat newlines as <br>
    'sane_lists',      # more predictable list handling
    'smarty',          # convert "quotes" to "smart" curly quotes
    'wikilinks',       # [[WikiLink]] syntax
    'admonition',      # !!! note "Title" blocks
]

md = markdown.Markdown(extensions=extensions)
html = md.convert(text)
meta = md.Meta  # dict of metadata if 'meta' extension is loaded

Pandoc Conversions — Markdown to HTML/PDF/DOCX, Custom Templates, YAML Front Matter

Pandoc is described as the “universal document converter.” It supports converting between over 40 file formats. For Markdown, it is the gold standard for producing publication-quality PDF, Word DOCX, EPUB, and HTML output.

Installation and Basic CLI Conversions

# Install Pandoc
# macOS
brew install pandoc
brew install --cask basictex   # For PDF output (smaller LaTeX install)

# Ubuntu/Debian
sudo apt-get install pandoc texlive-latex-base

# Windows (via winget)
winget install JohnMacFarlane.Pandoc

# Basic conversions
pandoc input.md -o output.html          # Markdown → HTML fragment
pandoc input.md -s -o output.html       # -s for standalone (full HTML page)
pandoc input.md -o output.pdf           # Markdown → PDF (needs LaTeX)
pandoc input.md -o output.docx          # Markdown → Word DOCX
pandoc input.md -o output.epub          # Markdown → EPUB
pandoc input.md -o output.odt           # Markdown → LibreOffice ODT
pandoc input.md -o output.rst           # Markdown → reStructuredText

# HTML → Markdown (reverse conversion)
pandoc input.html -f html -t markdown -o output.md

# Specify Markdown flavor
pandoc input.md --from=gfm -o output.html        # GFM input
pandoc input.md --from=markdown+smart -o out.pdf # With smart quotes

YAML Front Matter for Metadata

---
title: "My Report: Q4 2025 Analysis"
author:
  - Alice Johnson
  - Bob Smith
date: 2025-12-15
abstract: |
  This report covers the key findings from Q4 2025,
  including revenue trends and user growth metrics.
keywords:
  - quarterly report
  - analytics
  - growth
lang: en
bibliography: references.bib   # For academic citations
csl: apa.csl                   # Citation Style Language
toc: true                      # Generate table of contents
toc-depth: 3                   # TOC depth
numbersections: true           # Number headings (1.1, 1.2, etc.)
geometry: "margin=1in"         # Page margins for PDF
fontsize: 12pt
---

# Introduction

The body of your document starts here...

Custom Templates and Advanced Options

# Export the default HTML template to customize
pandoc -D html > my-template.html
# Edit my-template.html, then use it:
pandoc input.md --template=my-template.html -s -o output.html

# Adding a custom CSS file for HTML output
pandoc input.md -s --css=style.css -o output.html

# Generating a PDF with custom PDF engine
pandoc input.md -o output.pdf --pdf-engine=xelatex     # Better Unicode
pandoc input.md -o output.pdf --pdf-engine=wkhtmltopdf # HTML-based (no LaTeX)
pandoc input.md -o output.pdf --pdf-engine=weasyprint  # CSS Paged Media

# Batch conversion: all .md files in a directory to HTML
find . -name "*.md" -exec sh -c 'pandoc "$1" -s -o "${1%.md}.html"' _ {} \;

# Combine multiple Markdown files into one document
pandoc chapter1.md chapter2.md chapter3.md -o book.pdf

# Table of contents with custom depth
pandoc input.md --toc --toc-depth=2 -s -o output.html

# Include raw HTML pass-through
pandoc input.md --from=markdown+raw_html -o output.html

MDX (Markdown + JSX) — Next.js @next/mdx, Custom Components, contentlayer

MDX lets you use JSX in your Markdown content. This means you can import React components and use them directly in your .mdx files — creating interactive documentation, blog posts with live demos, and data-driven content that would be impossible with plain Markdown.

Setting up MDX in Next.js with @next/mdx

npm install @next/mdx @mdx-js/loader @mdx-js/react
npm install --save-dev @types/mdx

// next.config.mjs
import createMDX from '@next/mdx';

const withMDX = createMDX({
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
});

/** @type {import('next').NextConfig} */
const nextConfig = {
  pageExtensions: ['js', 'jsx', 'md', 'mdx', 'ts', 'tsx'],
};

export default withMDX(nextConfig);

// src/app/[lang]/blog/my-post/page.mdx
import { CodeBlock } from '@/components/CodeBlock';
import { Chart } from '@/components/Chart';

export const metadata = {
  title: 'My Interactive Blog Post',
  description: 'A post with live demos',
};

# Interactive Demo Post

Here is a **Markdown** heading followed by a React component:

<CodeBlock language="javascript">
  {JSON.stringify({ hello: 'world' }, null, 2)}
</CodeBlock>

And here is a live chart with data:

<Chart
  data={[
    { month: 'Jan', revenue: 4000 },
    { month: 'Feb', revenue: 3000 },
    { month: 'Mar', revenue: 5000 },
  ]}
  type="bar"
/>

## Continuing in Markdown

After the component, you can continue writing in **Markdown** normally.

MDX with next-mdx-remote (Dynamic MDX from CMS/Database)

npm install next-mdx-remote remark-gfm

// Server component: fetch MDX from CMS, serialize on server
import { MDXRemote } from 'next-mdx-remote/rsc';
import remarkGfm from 'remark-gfm';
import { CodeBlock } from '@/components/CodeBlock';
import { Alert } from '@/components/Alert';

// Components available inside your MDX content
const components = {
  CodeBlock,
  Alert,
  // Override default HTML elements
  h1: (props: React.HTMLAttributes<HTMLHeadingElement>) => (
    <h1 style={{ fontSize: '2rem', fontWeight: 800, marginTop: '2rem' }} {...props} />
  ),
  pre: (props: React.HTMLAttributes<HTMLPreElement>) => (
    <pre style={{ background: '#1e293b', color: '#e2e8f0', padding: '1rem', borderRadius: '8px', overflow: 'auto' }} {...props} />
  ),
};

// In a Server Component (App Router)
export async function BlogPost({ slug }: { slug: string }) {
  const post = await fetchPostFromCMS(slug); // your data fetching

  return (
    <MDXRemote
      source={post.content}
      options={{
        mdxOptions: {
          remarkPlugins: [remarkGfm],
          rehypePlugins: [],
        },
      }}
      components={components}
    />
  );
}

SEO-Optimized Markdown — Front Matter, Meta Description, Canonical URL, Structured Data

When Markdown powers a blog or documentation site, front matter and proper HTML output structure are critical for search engine visibility. Here is a complete guide to SEO-optimized Markdown content.

Complete Front Matter Structure

---
# Core SEO metadata
title: "Markdown Editor Online: Complete Syntax Guide (2025)"
description: "Master Markdown syntax with our online editor. Complete guide covering headers, lists, tables, code blocks, GFM extensions, and best practices for technical writers."
slug: "markdown-editor-online-guide"
canonical: "https://viadreams.cc/en/blog/markdown-editor-online-guide"

# Content metadata
date: 2025-02-27
lastModified: 2025-02-27
author: "DevToolBox Team"
category: "Developer Tools"
tags:
  - markdown
  - documentation
  - technical-writing
  - github

# Social media
ogTitle: "Markdown Syntax Complete Guide — DevToolBox"
ogDescription: "Master every Markdown feature: headers, tables, code blocks, GFM, and more."
ogImage: "https://viadreams.cc/images/markdown-editor-og.png"
twitterCard: "summary_large_image"

# Content flags
draft: false
featured: true
readingTime: 12

# Structured data hints (consumed by your build tool)
schema:
  type: "TechArticle"
  mainEntity: "Markdown"
---

Structured Data JSON-LD in Markdown-based Sites

// In Next.js: auto-generate Article schema from front matter
// src/app/[lang]/blog/[slug]/page.tsx

import { getPostBySlug } from '@/lib/posts';

export async function generateMetadata({ params }: { params: { slug: string; lang: string } }) {
  const post = await getPostBySlug(params.slug);

  return {
    title: post.frontmatter.title,
    description: post.frontmatter.description,
    alternates: {
      canonical: post.frontmatter.canonical,
    },
    openGraph: {
      title: post.frontmatter.ogTitle || post.frontmatter.title,
      description: post.frontmatter.ogDescription || post.frontmatter.description,
      images: [post.frontmatter.ogImage],
      type: 'article',
      publishedTime: post.frontmatter.date,
      modifiedTime: post.frontmatter.lastModified,
      tags: post.frontmatter.tags,
    },
    twitter: {
      card: post.frontmatter.twitterCard,
    },
  };
}

// In page component, inject Article schema
function ArticleSchema({ post }: { post: Post }) {
  const schema = {
    '@context': 'https://schema.org',
    '@type': 'TechArticle',
    headline: post.frontmatter.title,
    description: post.frontmatter.description,
    datePublished: post.frontmatter.date,
    dateModified: post.frontmatter.lastModified,
    author: {
      '@type': 'Organization',
      name: post.frontmatter.author,
      url: 'https://viadreams.cc',
    },
    publisher: {
      '@type': 'Organization',
      name: 'DevToolBox',
      url: 'https://viadreams.cc',
    },
    mainEntityOfPage: {
      '@type': 'WebPage',
      '@id': post.frontmatter.canonical,
    },
  };

  return (
    <script
      type="application/ld+json"
      dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
    />
  );
}

SEO Best Practices for Markdown Content

# SEO Checklist for Markdown Documents

## Heading structure (critical for crawlers)
# H1 — One per page, contains primary keyword
## H2 — Major sections, contain secondary keywords
### H3 — Sub-topics, support H2 sections

## Image alt text (required for accessibility + SEO)
![Markdown editor showing live preview split view](./editor-screenshot.png)

## Internal linking (boosts PageRank flow)
Learn more about [JSON formatting](/en/tools/json-formatter) and
[Base64 encoding](/en/tools/base64-encoder-decoder).

## Keyword density — natural inclusion, not stuffing
- Primary keyword in H1, first paragraph, and at least one H2
- Secondary keywords in H3s and body paragraphs
- LSI keywords naturally throughout

## Content length guidelines
- Blog post: 1500-3000 words for comprehensive coverage
- Tutorial: 2000-5000 words with working code examples
- Reference guide: organized, scannable, 1000-2500 words

## URL slug best practices (from front matter)
slug: "markdown-editor-online-guide"  ✅ Descriptive, hyphenated
slug: "post-123"                       ❌ No keywords
slug: "markdown_editor_online_guide"  ❌ Underscores (use hyphens)

## Meta description rules
# ✅ Good: 140-160 characters, includes CTA, primary keyword
description: "Master Markdown syntax with our free online editor. Complete 2025 guide covering tables, code blocks, GFM, and MDX for developers."

# ❌ Bad: Too short, no keyword
description: "Learn Markdown."