SKIP TO CONTENT
Uroš Karić
←Back to all essays
ESSAY·MDX

MDX Components Showcase

Every custom MDX component on this site, with a working example of each: callouts, terminals, file trees, diagrams, quotes, stats.

UROŠ KARIĆ/JAN 20, 2025/4 MIN READ

This post demonstrates every custom MDX component available for writing blog posts. They all fit the terminal brutalist aesthetic of the site.

01 // Callout Boxes

Callouts pull important information out of the body text. Warnings, tips, notes.

iINFO

This is an info callout. Use it for general information that readers should know about.

!WARNING

This is a warning callout. Use it when readers need to be careful about something.

*TIP

This is a tip callout. Share helpful shortcuts or best practices here.

xDANGER

This is a danger callout. Use sparingly for critical warnings that could cause data loss or security issues.

#Custom Title

You can also customize the title of any callout type.

02 // Terminal Output

For showing actual terminal/CLI output, use the Terminal component:

installing dependencies
zsh
Terminal window
$ pnpm add gsap motion


Packages: +2
++
Progress: resolved 786, reused 750, downloaded 0, added 2, done


dependencies:
+ gsap 3.12.5
+ motion 11.15.0


Done in 1.2s
git status
zsh
Terminal window
$ git status
On branch main
Your branch is up to date with 'origin/main'.


Changes not staged for commit:
  modified:   src/components/Header.tsx
  modified:   src/pages/index.astro


Untracked files:
  src/components/mdx/

03 // File Tree

Display project structures clearly:

project structure
src/
├── components/
│   ├── mdx/
│   │   ├── Callout.astro
│   │   ├── Terminal.astro
│   │   ├── FileTree.astro
│   │   └── index.ts
│   ├── react/
│   │   └── Header.tsx
│   └── ui/
│       └── Navigation.astro
├── content/
│   └── blog/
│       └── mdx-components-showcase.mdx
├── layouts/
│   └── BlogLayout.astro
└── pages/
    └── index.astro

04 // Keyboard Shortcuts

Reference keyboard shortcuts inline with the Kbd component:

Press Cmd + K to open the command palette.

Common shortcuts:

  • Save file: Cmd + S
  • Undo: Cmd + Z
  • Search: Cmd + F
  • Terminal: Ctrl + `

05 // Step-by-Step Instructions

Guide readers through processes:

Setting up a new project

Create the project directory

Run mkdir my-project && cd my-project to create and enter your new project directory.

Initialize the package

Run pnpm init to create a package.json file with default values.

Install dependencies

Add your core dependencies with pnpm add astro react @astrojs/react.

Start development

Launch the dev server with pnpm dev and open localhost:4321 in your browser.

06 // Link Cards

Create link previews for external resources:

Astro

The web framework for content-driven websites. Build fast, content-focused websites with Astro's island architecture.

astro.build

Claude Code

An agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster.

github.com

07 // Collapsible Sections

Hide optional or advanced content that readers can expand:

If you encounter issues, try these solutions:

  1. Clear the .astro cache directory
  2. Delete node_modules and reinstall
  3. Check for TypeScript errors with pnpm tsc
  4. Verify your Node.js version is 18+

08 // Diff / Code Changes

Show before and after changes:

-+config update
astro.config.mjs
export default defineConfig({
  output: 'static',
  output: 'hybrid',
  adapter: cloudflare(),
   integrations: [
     react(),
    mdx(),
   ],
});

09 // Figures with Captions

Display images with proper captions:

Code on a monitor
// Writing code at 2am hits different

10 // Mermaid Diagrams

Create diagrams directly in your markdown:

request flow
Loading diagram...
state machine
Loading diagram...
sequence diagram
Loading diagram...

Combining Components

Components work great together. Here’s a real example:

*TIP

Always validate user input before sending to the server to improve UX and reduce unnecessary API calls.

Adding form validation

Install validation library

Run pnpm add zod to add Zod for schema validation.

Define your schema

Create a schema that matches your form fields.

Validate on submit

Parse the form data through your schema before submitting.

import { z } from 'zod';


const userSchema = z.object({
  email: z.string().email('Invalid email address'),
  password: z.string().min(8, 'Password must be at least 8 characters'),
  name: z.string().min(2, 'Name is required'),
});


type User = z.infer<typeof userSchema>;


function handleSubmit(data: unknown) {
  const result = userSchema.safeParse(data);


  if (!result.success) {
    console.error(result.error.flatten());
    return;
  }


  // data is now typed as User
  submitToAPI(result.data);
}
!WARNING

Never trust client-side validation alone. Always validate on the server too!

11 // Pull Quotes

Emphasize a phrase from your own writing with a large pull quote:

Pull quotes break up long text and give readers something to remember.

12 // Attributed Quotes

For quoting books, people, or external sources with proper attribution:

Premature optimization is the root of all evil.

—Donald KnuthThe Art of Computer Programming (1968)

Talk is cheap. Show me the code.

—Linus Torvalds

13 // Asides

For tangential thoughts that don’t interrupt the main flow:

14 // Stat Highlights

For emphasizing a statistic or data point:

84%use AI tools
46%distrust output
2xfaster deploys

15 // Inline Terms

For definitions, translations, or terms being discussed:

The German word heimlich means homely or familiar, but also hidden.

Use it for ironic or sarcastic usage too: Running chmod 777 because it fixed the problem.

16 // Inline Stats

For statistics that deserve emphasis in running text:

84% of developers now use AI tools, yet only 33% trust the output. That’s a 70% decline from the previous year.

X↗BLUESKY↗
←PREVIOUSThe Unreasonable Effectiveness of BrutalismNEXT→Generating OG Images at Build Time with Satori