#MDX#COMPONENTS#DOCUMENTATION

MDX Components Showcase

Jan 20, 2025

8 min Read

ID: MDX-COMPONENTS-SHOWCASE

This post demonstrates all the custom MDX components available for writing blog posts. Each component is designed to fit the terminal brutalist aesthetic of this site.

01 // Callout Boxes

Callouts are perfect for highlighting important information, warnings, tips, or notes.

i INFO

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.

x DANGER

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

$ 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

$ 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 http://localhost:4321.

06 // Link Cards

Create rich 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:

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

08 // Diff / Code Changes

Show before and after changes:

- + config update

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-world 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!

// END_OF_FILE