How I style my blog: a guide to all MDX components

November 29, 2024 (7mo ago)

This guide shows all the available MDX components and styling patterns used in this blog. Useful if you are curious or planning to write something similar.

Headers (H2)

Subheaders (H3)

Subheaders (H4)

Tweets

Embed tweets using the StaticTweet component:

Multiple tweets in a sequence:

Paragraphs and text

Regular paragraph text with bold text and italic text. You can also use inline code for small code snippets or technical terms.

Here's a second paragraph to show spacing. Text flows naturally and maintains good readability with proper line height and spacing.

Lists

Bullet points

  • First bullet point item
  • Second bullet point with some longer text to show how it wraps
  • Third item with inline code
  • Fourth item with bold text

Numbered lists

  1. First numbered item
  2. Second numbered item with more detail
  3. Third item explaining something important
  4. Final numbered item

External links work like this: Next.js documentation.

Internal links to other posts: A Journey with Gemini 2.5 CLI.

Links will have green underlines and green text on hover, matching the site theme.

Code blocks

Single line commands

npm install @next/mdx
git status

Multi-line code with title

export default function Gallery() {
  return (
    <div className="max-w-2xl mx-auto py-16 px-4">
      <div className="grid grid-cols-1 gap-y-10 sm:grid-cols-2">
        {/* Content goes here */}
      </div>
    </div>
  );
}

TypeScript examples

type Image = {
  id: number;
  href: string;
  imageSrc: string;
  name: string;
  username: string;
};

Configuration files

module.exports = {
  content: [
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  theme: {
    extend: {},
  },
  plugins: [require('@tailwindcss/aspect-ratio')],
};

Environment variables

NEXT_PUBLIC_SUPABASE_URL=your-value-here
SUPABASE_SERVICE_ROLE_KEY=your-value-here
REVALIDATE_SECRET=your-secret-here

Images

Standard images

Example of Next.js image gallery with Supabase and Tailwind

Images with custom sizing

Supabase database table example

Callouts and quotes

Callout boxes

💡

This is a callout box with an emoji. Use these for important tips, warnings, or additional information that stands out from the main content.

⚠️

Warning callouts are useful for highlighting potential issues or things to be careful about.

✅

Success or tip callouts work well for positive information or pro tips.

Block quotes

This is a blockquote. Use these for citing other sources, highlighting important statements, or emphasizing key points from external sources.

Inline code vs code blocks

Use inline code for:

  • Variable names like useState or process.env.NODE_ENV
  • File names like package.json or next.config.js
  • Short code snippets like npm install
  • Technical terms like getStaticProps

Use code blocks for:

  • Complete functions or components
  • Multi-line configurations
  • Command sequences
  • Code examples that need syntax highlighting

Text formatting

  • Bold text for emphasis and important terms
  • Italic text for subtle emphasis or technical terms
  • Code formatting for technical terms and variables
  • Regular text for general content

Separating sections

Use horizontal spacing by leaving blank lines between sections. The CSS handles proper spacing automatically.

For major topic changes, use H2 headers. For subtopics, use H3 and H4 headers as needed.

You can also use markdown horizontal rules --- to create visual separation between major sections:

Like this. This creates a subtle line that helps separate content visually.

Best practices

Writing style

  • Keep paragraphs concise and focused
  • Explain technical concepts clearly
  • Include practical examples
  • Link to relevant external resources

Code examples

  • Always include file names in code block titles when relevant
  • Use proper syntax highlighting by specifying the language
  • Keep code examples focused and minimal
  • Comment complex code when necessary

Images

  • Always include descriptive alt text
  • Use appropriate sizing (width/height)
  • Add priority for above-the-fold images
  • Organize images in /public/images/[post-slug]/ folders
  • Use descriptive link text (not "click here")
  • Link to official documentation when referencing tools
  • Internal links should use relative paths
  • External links open in new tabs automatically

Technical notes

This blog uses:

  • MDX for rich content with React components
  • Custom styling with Tailwind CSS and custom CSS
  • Dark mode support with consistent theming
  • Syntax highlighting for code blocks
  • Responsive images with Next.js Image component
  • Tweet embedding with react-tweet
  • Green accent colors #788C5D for links and interactive elements

All components automatically adapt to both light and dark themes, maintaining readability and visual consistency across the site.