Markdown & MDX Style Guide: Complete Formatting & Embed Reference |...

Welcome to the CuriousVolt Markdown & MDX Style Guide. This live reference demonstrates all the typography, callout components, media embeds, and code formatting features available across both the blog and project sections.

1. Clean Rounded Callouts (No Boring Left Line)

Callouts now feature smooth rounded corners (rounded-2xl), subtle elevated card backgrounds, and category-specific icons. The old left border line has been replaced with modern, balanced all-around card styling.

Information Note

Use this for contextual explanations, background details, or architectural notes that support the main text without interrupting the reading flow.

Pro Tip / Best Practice

Performance optimizations and tactical advice look best in tip callouts. For example: leverage client-side PDF rendering to reduce server compute by 90%.

Product Decision

When writing product case studies, use the decision callout to highlight key strategic trade-offs, scope decisions, and core product bets.

Warning / Edge Case

Alert readers to potential pitfalls, breaking API changes, or critical security requirements.

Important Requirement

Use for essential prerequisites, non-negotiable compliance rules, or key metrics milestones.

How to use Callout in your MDX:

1
import Callout from '@/components/Callout.astro'
2

3
<Callout type="tip" title="Pro Tip">
4
  Your custom advice or explanation goes here.
5
</Callout>

2. Standard Blockquotes

Standard Markdown blockquotes (> text) also render with the new borderless-left, rounded card aesthetic:

“Simplicity is about subtracting the obvious and adding the meaningful. A great user interface gets out of the way and lets the product speak for itself.”

— John Maeda, The Laws of Simplicity

3. Lists & Hierarchies

Bulleted Lists (Unordered)

Primary Product Pillars:
- Frictionless guest-first onboarding
- Real-time milestone progress tracking
- Instant automated tax compliance exports
Engineering Highlights:
- Sub-second edge response times
- Normalized document schemas for audit integrity
- Full TypeScript type safety across frontend and API layers

Numbered Lists (Step-by-Step Flow)

User Discovery: Reader discovers open-source project via GitHub or technical blog post.
Interactive Preview: User explores the live interactive demo and inspects product decisions.
Execution: Checkout or authentication completes in under 30 seconds with zero friction.
Instant Confirmation: System delivers an automated, audit-ready PDF receipt to the client.

4. Code Blocks & Syntax Highlighting

Powered by Expressive Code, code blocks feature line numbers, copy buttons, file titles, and dark/light adaptive syntax highlighting:

1
export interface FunnelMetric {
2
  step: string;
3
  conversionRate: number;
4
  dropoffPercentage: number;
5
}
6

7
export function computeFunnelHealth(events: number[]): FunnelMetric[] {
8
  // Highlighted lines emphasize critical algorithms
9
  return events.map((count, idx) => ({
10
    step: `Phase ${idx + 1}`,
11
    conversionRate: (count / (events[0] || 1)) * 100,
12
    dropoffPercentage: 100 - (count / (events[0] || 1)) * 100,
13
  }));
14
}

1
# Clone and run the portfolio locally
2
git clone https://github.com/curiousvolt/portfolio.git
3
cd portfolio
4
npm install
5
npm run dev

Inline code is styled cleanly with rounded badges: const role = 'pm', npm run build, and GET /api/v1/projects.

5. Google Slides Embed

Embed any interactive Google Slides deck with a responsive 16:9 aspect ratio, slide navigation controls, and fullscreen view:

Product Strategy & Architecture Overview

Open Fullscreen

How to use Google Slides in your MDX:

1
import GoogleSlides from '@/components/GoogleSlides.astro'
2

3
<GoogleSlides
4
  src="https://docs.google.com/presentation/d/YOUR_PRESENTATION_ID/embed"
5
  title="Your Presentation Title"
6
/>

6. PDF Document Embed

Embed product requirement documents (PRDs), architectural whitepapers, or logistics reports with built-in download and fullscreen controls:

Product Requirements Document (PRD)

Download Open Fullscreen

How to use DocumentEmbed in your MDX:

1
import DocumentEmbed from '@/components/project/DocumentEmbed.astro'
2

3
<DocumentEmbed
4
  src="/path-to-document.pdf"
5
  title="Architecture Specification"
6
  height="560px"
7
/>

7. Data Tables

Tables are rendered with rounded corners, subtle headers, clean borders, and full mobile horizontal scrolling:

Phase	Milestone Objective	Target Deliverable	Status
Q1	User Research & Discovery	15 User interviews & Persona maps	Complete
Q2	MVP Architecture	Node.js REST API + React UI	Complete
Q3	Production Hardening	Automated PayPal capture & PDF generation	Shipped
Q4	Scale & Analytics	Admin telemetry dashboard & CSV export	Active

8. Mathematical Formulas (LaTeX / KaTeX)

Support for both inline equations like $E = mc^2$ and complex mathematical formulas:

$\sigma(z) = \frac{1}{1 + e^{-z}}$

$\text{Precision} = \frac{\text{True Positives}}{\text{True Positives} + \text{False Positives}}$

9. Collapsible Details & FAQs

How do I switch perspectives on project pages?

Project pages support dual perspectives: Product (strategy, metrics, personas, decks) and Technical (architecture, schemas, API endpoints). Visitors can toggle tabs directly on the page, or view the Product perspective automatically via ?role=pm.

Summary Checklist for MDX Authors

Callouts: Use <Callout type="tip | note | decision | warning | important"> instead of boring lines.
Presentations: Use <GoogleSlides src="..." title="..." /> for 16:9 interactive slides.
PDFs: Use <DocumentEmbed src="..." title="..." /> for whitepapers and documentation.
Code: Use standard triple backticks with language and optional title="...".
Tables: Use standard markdown pipe tables; they are automatically styled and responsive.