---
title: Markdown Tips and Tricks — isHistory
description: Handy Markdown tips and tricks for writing better content in Astro, including callouts, wiki links, math, and more.
url: "https://ishistory.org/blog/markdown-tips"
type: static
generatedAt: "2026-06-01T11:07:55.672Z"
---

# Markdown Tips and Tricks
    May 29, 2026    Astro Explorer    3 min read
Handy Markdown tips and tricks for writing better content in Astro, including callouts, wiki links, math, and more.

markdown, tips, math, callouts

May 29, 2026
   [markdown](/tags/#tag-markdown)[tips](/tags/#tag-tips)[math](/tags/#tag-math)[callouts](/tags/#tag-callouts)      On this page
## Level Up Your Markdown

Markdown is simple by design, but there are plenty of tricks that can make your content even better. Here are some tips that work great with Astro’s classic Markdown engine and the plugins in this project.

## 1. Use Callouts for Important Information

With `rehype-callouts`, you get Obsidian-style callouts. Use them to draw attention to important information:
 Note
Callouts are perfect for highlighting important information that readers shouldn’t miss.
 Tip
You can use callouts to suggest best practices or helpful shortcuts.
 Warning
Use warning callouts to alert readers about common pitfalls or breaking changes.
 Important
Critical information that must be followed goes in important callouts.
 Example
Callouts support many types including note, tip, warning, important, example, question, success, failure, and more.

## 2. Wiki Links for Interconnected Content

Connect your pages using wiki links instead of traditional relative URLs:

 - Traditional: `[Getting Started](/blog/getting-started/)`
 - Wiki link: `[[getting-started]]` → [getting-started](/blog/getting-started/)
  Tip
Wiki links are easier to maintain because they reference content by name, not file path. If you reorganize your pages, you only need to update the permalink mapping, not every link.

You can also use aliases for cleaner link text:

 - `[[configuration-deep-dive|config guide]]` → [config guide](/blog/configuration-deep-dive/)

## 3. Expressive Code Features

The `astro-expressive-code` integration gives you super-powered code blocks:

**Line numbers:**


*server.ts*

```
import express from 'express';
const app = express();const PORT = 3000;
app.get('/', (req, res) => {  res.json({ message: 'Hello from Astro!' });});
app.listen(PORT, () => {  console.log(`Server running on port ${PORT}`);});
```

**Marked and highlighted lines:**


*config.js*

```
const siteName = "Astro Blog";const version = "6.4.2";const engine = "classic"; // This line is markedconst features = [  "tailwind",  // These lines are inserted  "expressive-code",];
```

**Diff-style highlighting:**


*changes.diff*

```
const oldWay = "shiki";const newWay = "expressive-code";
Astro.glob('./*.md');import.meta.glob('./*.md', { eager: true });
```

## 4. Math with KaTeX

This project supports **LaTeX math** via `remark-math` and `rehype-katex`. You can write inline math or display equations:

**Inline math:** The Euler identity eiπ+1=0 is one of the most beautiful equations in mathematics.

**Display math:**
 ∫−∞∞​e−x2dx=π​
**The quadratic formula:**
 x=2a−b±b2−4ac​​
**Maxwell’s equations in differential form:**
 ∇⋅E∇⋅B∇×E∇×B​=ε0​ρ​=0=−∂t∂B​=μ0​J+μ0​ε0​∂t∂E​​ Tip
Use `$...$` for inline math and `$$...$$` for display (block) math. KaTeX supports a wide range of LaTeX commands — see the [KaTeX supported functions](https://katex.org/docs/supported) reference.

## 5. Extended Tables

Use `^` for rowspan and `>` for colspan in tables:

| Category | Plugin | Type |
| --- | --- | --- |
| Markdown | remark-math | Math parsing |
| remark-extended-table | Extended tables |
| @flowershow/remark-wiki-link | Wiki links |
| Rendering | rehype-katex | Math display |
| rehype-callouts | Callout boxes |
| astro-expressive-code | Code blocks |

## 6. Use HTML When Needed

Markdown doesn’t cover every HTML element. When you need something more — like a detail/summary collapse or a custom container — you can mix HTML directly into your Markdown:


**

```
<details>  <summary>Click to expand</summary>  This content is hidden by default!</details>
```

## 7. Task Lists

You can create task lists (checkboxes) using brackets:

 - Set up Astro project
 - Configure classic Markdown engine
 - Add TailwindCSS via @astrojs/tailwind
 - Set up astro-expressive-code
 - Configure wiki-link plugin
 - Add remark-math + rehype-katex
 - Configure rehype-callouts
 - Add remark-extended-table
 - Add more features
 - Deploy to production

## Keep Writing!

The best way to get comfortable with Markdown is to write with it regularly. Astro makes it easy — just create `.md` files in `src/content/blog/` and let the framework handle the rest. Check out [getting-started](/blog/getting-started/) for the basics or [configuration-deep-dive](/blog/configuration-deep-dive/) for advanced config.

### Share this post