wiki/public/raw/markdown-with-code-examples.md

Writing Markdown with Code Examples

A complete reference for writing markdown with links, code blocks, images, tables, and formatting. Copy examples directly into your posts.

---

Type: post Date: 2025-12-14 Reading time: 5 min read Tags: markdown, tutorial, code

Writing Markdown with Code Examples

This post demonstrates how to write markdown content with code blocks, tables, and formatting. Use it as a reference when creating your own posts.

Frontmatter

Every post starts with frontmatter between --- delimiters:

---
title: "Your Post Title"
description: "A brief description for SEO"
date: "2025-01-17"
slug: "your-url-slug"
published: true
tags: ["tag1", "tag2"]
readTime: "5 min read"
---

Code Blocks

TypeScript

import { query } from "./_generated/server";
import { v } from "convex/values";

export const getPosts = query({
  args: {},
  returns: v.array(
    v.object({
      _id: v.id("posts"),
      title: v.string(),
      slug: v.string(),
    }),
  ),
  handler: async (ctx) => {
    return await ctx.db.query("posts").collect();
  },
});

React Component

import { useQuery } from "convex/react";
import { api } from "../convex/_generated/api";

export function PostList() {
  const posts = useQuery(api.posts.getPosts);

  if (posts === undefined) {
    return <div>Loading...</div>;
  }

  return (
    <ul>
      {posts.map((post) => (
        <li key={post._id}>
          <a href={`/${post.slug}`}>{post.title}</a>
        </li>
      ))}
    </ul>
  );
}

Bash Commands

# Install dependencies
npm install

# Start development server
npm run dev

# Sync posts to Convex (development)
npm run sync

# Sync posts to Convex (production)
npm run sync:prod

# Deploy to production
npm run deploy

JSON

{
  "name": "markdown-blog",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "sync": "npx ts-node scripts/sync-posts.ts"
  }
}

Inline Code

Use backticks for inline code like npm install or useQuery.

Reference files with inline code: convex/schema.ts, src/pages/Home.tsx.

Tables

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run sync	Sync markdown to Convex (dev)
npm run sync:prod	Sync markdown to Convex (prod)
npx convex dev	Start Convex dev server

Lists

Unordered

• Write posts in markdown
• Store in Convex database
• Deploy to Netlify
• Updates sync in real-time

Ordered

1. Fork the repository
2. Set up Convex backend
3. Configure Netlify
4. Start writing

Blockquotes

Markdown files in your repo are simpler than a CMS. Commit changes, review diffs, roll back anytime. AI agents can create posts programmatically. No admin panel needed.

Links

Markdown supports several link formats.

Basic links

[Link text](https://example.com)

Result: Convex Docs

Internal links

Link to other posts and pages using the slug:

[Setup Guide](/setup-guide)
[About](/about)
[Changelog](/changelog)

Result: Setup Guide

Links with titles

Add a title that appears on hover:

[Convex](https://convex.dev "Real-time backend")

Result: Convex

Reference-style links

For cleaner markdown when using the same link multiple times:

Read the [Convex docs][convex] or check the [API reference][convex].

[convex]: https://docs.convex.dev

Autolinks

URLs and email addresses in angle brackets become clickable:

<https://markdown.fast>
<hello@example.com>

Linking to headings

Link to sections within the same page using the heading ID:

[Jump to Code Blocks](#code-blocks)
[See the Tips section](#tips)

Result: Jump to Code Blocks

Emphasis

Use bold for strong emphasis and italics for lighter emphasis.

Horizontal Rule

---

Images

Place images in public/images/ and reference them with absolute paths.

Basic image

![Screenshot of the setup guide](/images/setupguide.png)

Image with title

![Dashboard view](/images/v17.png "Version 17 dashboard")

Featured images in frontmatter

Add an image to your post frontmatter for card views and social sharing:

---
image: "/images/my-post-image.png"
---

The image appears as a thumbnail in card view and as the Open Graph image when shared.

Image sizing

For best results:

• Blog images: 1200x630px (standard OG size)
• Author avatars: 200x200px (displays as circle)
• Card thumbnails: Square images work best (auto-cropped to center)

Nested lists

Indent with two spaces for nested items:

- Parent item
  - Child item
  - Another child
    - Grandchild item
- Back to parent level

Result:

• Parent item
  • Child item
  • Another child
    • Grandchild item
• Back to parent level

Mixed list types

Combine ordered and unordered lists:

1. First step
   - Sub-point A
   - Sub-point B
2. Second step
   - Another sub-point

Result:

1. First step
   • Sub-point A
   • Sub-point B
2. Second step
   • Another sub-point

Escaping characters

Use backslash to display literal markdown characters:

\*not italic\*
\`not code\`
\[not a link\]

Result: *not italic* and `not code`

Line breaks

End a line with two spaces for a soft break.
Or use a blank line for a new paragraph.

First line with two trailing spaces  
Second line (soft break)

New paragraph (blank line above)

Combining emphasis

Stack formatting for combined effects:

**_bold and italic_**
`code with **no bold** inside`

Result: bold and italic

File Structure Reference

content/blog/
├── about-this-blog.md
├── markdown-with-code-examples.md
├── setup-guide.md
└── your-new-post.md

Tips

1. Keep slugs URL-friendly (lowercase, hyphens)
2. Set published: false for drafts
3. Run npm run sync after adding posts (or npm run sync:prod for production)
4. Use descriptive titles for SEO

Strikethrough

Use double tildes for strikethrough text:

~~deleted text~~

Result: deleted text

Code in headings

You can include inline code in headings:

## Using the `useQuery` hook

Tables with alignment

Control column alignment with colons:

| Left | Center | Right |
| :--- | :----: | ----: |
| L    |   C    |     R |

Left	Center	Right
L	C	R

Collapsible sections

Use HTML <details> and <summary> tags to create expandable/collapsible content:

Basic toggle

<details>
<summary>Click to expand</summary>

Hidden content goes here. You can include:

- Lists
- **Bold** and _italic_ text
- Code blocks
- Any markdown content

</details>

Click to expand

Hidden content goes here. You can include:

• Lists
• Bold and italic text
• Code blocks
• Any markdown content

Expanded by default

Add the open attribute to start expanded:

<details open>
<summary>Already expanded</summary>

This section starts open. Users can click to collapse it.

</details>

Already expanded

This section starts open. Users can click to collapse it.

Toggle with code

<details>
<summary>View the code example</summary>

```typescript
export const getPosts = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("posts").collect();
  },
});

```

View the code example

export const getPosts = query({
  args: {},
  handler: async (ctx) => {
    return await ctx.db.query("posts").collect();
  },
});

Nested toggles

You can nest collapsible sections:

<details>
<summary>Outer section</summary>

Some content here.

<details>
<summary>Inner section</summary>

Nested content inside.

</details>

</details>

Outer section

Some content here.

Inner section

Nested content inside.

Multi-line code in lists

Indent code blocks with 4 spaces inside list items:

1. First step:

   ```bash
   npm install
   ```

2. Second step:

   ```bash
   npm run dev
   ```

Quick reference

Syntax	Result
**bold**	bold
_italic_	italic
~~strike~~	strike
`code`	code
[link](url)	link
	image
> quote	blockquote
---	horizontal rule