Markdown Tips and Tricks

May 29, 2026 Astro Explorer 3 min read
markdown tips math 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
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:

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 marked
const 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 is one of the most beautiful equations in mathematics.

Display math:

The quadratic formula:

Maxwell’s equations in differential form:

Tip

Use $...$ for inline math and $$...$$ for display (block) math. KaTeX supports a wide range of LaTeX commands — see the KaTeX supported functions reference.

5. Extended Tables

Use ^ for rowspan and > for colspan in tables:

CategoryPluginType
Markdownremark-mathMath parsing
remark-extended-tableExtended tables
@flowershow/remark-wiki-linkWiki links
Renderingrehype-katexMath display
rehype-calloutsCallout boxes
astro-expressive-codeCode 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 for the basics or configuration-deep-dive for advanced config.

Share this post