took out boiler

2026-06-03 22:37:41 -05:00
parent 6a35cc25d4
commit 975c1bec9b
1 changed files with 0 additions and 314 deletions
--- a/content/posts/ultimate-mdx-showcase.mdx
+++ b/content/posts/ultimate-mdx-showcase.mdx
@@ -1,314 +0,0 @@
 ---
 title: "The Ultimate MDX Showcase"
 date: "2026-06-03"
 excerpt: "A comprehensive demo exercising every Markdown and MDX feature supported by this blog — from typography to math, code, callouts, tables, images, and more."
 tags:
  - Design
  - Next.js
  - Math
  - Code
  - Web Dev
 author: "Krishna"
 coverImage: "/starter-showcase.svg"
 ---
 ## Introduction
 Welcome to the ultimate showcase of Markdown and MDX features available on this blog. This post demonstrates the full spectrum of formatting, technical, and interactive elements at your disposal — from basic text styling to advanced math rendering and custom callout components.
 Whether you're writing a tutorial, sharing code snippets, or documenting design decisions, the content pipeline supports rich, engaging technical writing. Check out the [Posts archive](/posts/) for more articles, or dive into the [MDX Documentation](https://mdxjs.com/) to learn more about the underlying technology.
 This page uses **bold text**, *italic text*, ***bold and italic*** together, and ~~strikethrough~~ to show you the range of inline formatting available. You can also include inline code like `console.log('hello')` directly within a sentence.
 ---
 ## Typography and Text
 ### Basic Formatting
 Good typography is the foundation of readable content. Markdown gives you clean semantic markup without the clutter of HTML tags. Here's how the different heading levels stack up — each one serves a distinct purpose in organizing your content for both readers and the table of contents.
 #### Sub-section Heading
 Sub-sections help break down larger topics into digestible pieces. They're especially useful when a single section covers multiple related concepts.
 ##### Minor heading
 Even smaller subdivisions work seamlessly, allowing granular organization without overwhelming your document structure.
 ###### Smallest heading
 The smallest heading level is rarely needed, but it's there when you need maximum granularity.
 > This is a blockquote with multiple paragraphs. Blockquotes are perfect for highlighting important passages, citing sources, or setting aside reflective commentary.
 >
 > Second paragraph of the blockquote. You can include as many paragraphs as needed within a single blockquote, and each one will render with the same styling.
 ### Lists
 Lists are essential for organizing information. Markdown supports several list types that work beautifully together.
 **Ordered lists are great for step-by-step instructions:**
 1. First item — start with the initial setup
 2. Second item — build on the foundation
   - Nested unordered item for details
   - Another nested item with extra context
 3. Third item — finalize and review
 **Unordered lists work well for grouping related items:**
 - Item one — the primary category
  - Nested item A — specific detail
  - Nested item B — related detail
 - Item two — the secondary category
 ### Task Lists
 Task lists combine checkboxes with content, making them perfect for progress tracking:
 - [x] Build the MDX pipeline
 - [x] Add code highlighting
 - [x] Implement callouts
 - [ ] Write comprehensive tests
 - [ ] Deploy to production
 ## Code and Technical Content
 Code blocks are one of the most powerful features of MDX. They support language-specific syntax highlighting, line numbers, title bars, and selective line highlighting.
 ### TypeScript Example
 Here's a Next.js root layout component with highlighted lines showing the key structural elements:
 ```tsx title="app/layout.tsx" {1,3-5}
 import { ThemeProvider } from '@/components/ThemeProvider';
 export default function RootLayout({
  children,
 }: {
  children: React.ReactNode;
 }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
 }
 ```
 Lines 1 and 3-5 are highlighted to draw attention to the import statement and the function signature — the two most important parts for understanding this component's contract.
 ### Python Example
 The same highlighting concept works across all supported languages:
 ```python title="utils.py" {2,4}
 def calculate_fibonacci(n: int) -> list[int]:
    """Calculate Fibonacci sequence up to n terms."""
    if n <= 0:
        return []
    sequence = [0, 1]
    while len(sequence) < n:
        sequence.append(sequence[-1] + sequence[-2])
    return sequence
 print(calculate_fibonacci(10))
 ```
 Line 2 highlights the docstring, and line 4 highlights the early return — both critical for understanding the function's behavior at the boundaries.
 ### Bash Example
 Shell scripts get the same treatment:
 ```bash title="deploy.sh"
 #!/bin/bash
 echo "Building project..."
 bun run build
 echo "Deployment complete!"
 ```
 ### Why Code Matters in Technical Writing
 Well-formatted code blocks transform abstract explanations into concrete, actionable examples. They let readers copy, paste, and experiment immediately. Combined with syntax highlighting and line numbers, your technical content becomes both educational and practical.
 ## Visual Elements
 ### Images from Public Directory
 Images help illustrate complex concepts and break up text-heavy content. Here's how they look in practice:
 ![Showcase diagram](/starter-showcase.svg)
 ![Design diagram](/starter-diagram.svg)
 Both images are stored in the `public/` directory and referenced using absolute paths starting with `/`. This approach ensures they're properly bundled and available during static site generation.
 ## Tables
 Tables are essential for presenting structured data. Markdown tables support headers, alignment, and complex formatting.
 ### Feature Comparison
 | Feature | Basic | Advanced | Expert |
 |---------|-------|----------|--------|
 | Markdown | ✅ | ✅ | ✅ |
 | Code Highlighting | ❌ | ✅ | ✅ |
 | Math Rendering | ❌ | ❌ | ✅ |
 | Custom Components | ❌ | ✅ | ✅ |
 | Callouts | ❌ | ❌ | ✅ |
 ### Technical Specifications
 | Property | Value | Type |
 |----------|-------|------|
 | `max-width` | `72ch` | CSS |
 | `scroll-offset` | `7.5rem` | CSS |
 | `line-height` | `1.75` | Tailwind |
 Tables work especially well for comparing options or documenting API parameters. The GFM table syntax renders cleanly across all Markdown processors.
 ## Mathematics
 Mathematical notation elevates technical writing, making it possible to express precise relationships and formulas inline.
 ### Inline Equations
 You can embed equations directly within your text. The famous equation $E = mc^2$ changed physics forever. Similarly, the sum of squares formula $\sum_{i=0}^{n} i^2 = \frac{n(n+1)(2n+1)}{6}$ is useful in algorithm analysis and statistics.
 ### Display Equations
 For more complex expressions, display equations render on their own line with centered formatting:
 The quadratic formula:
 $$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$$
 Bayes' theorem:
 $$P(A|B) = \frac{P(B|A) \cdot P(A)}{P(B)}$$
 These equations are rendered using KaTeX, which provides fast and beautiful math typesetting for the web.
 ## Callouts and Admonitions
 Callouts are special content blocks that draw attention to important information. They come in four distinct styles, each serving a different communicative purpose.
 :::note title="About Callouts"
 Callouts are special blocks that draw attention to important information. They are rendered using the `remark-directive` plugin and a custom `Callout` component.
 This is a second paragraph within the note callout, demonstrating multi-paragraph support. Callouts can contain any valid Markdown content, including code blocks, lists, and links.
 :::
 :::tip title="Pro Tip"
 You can include inline code in callouts, like `npm install package-name`, to make instructions clearer and more actionable for readers. Use tips for best practices, shortcuts, and things that will make someone's life easier.
 :::
 :::warning title="Heads Up"
 This feature is still experimental. While it works in most cases, you may encounter edge cases with complex nested content.
 Always test your content thoroughly before publishing. Warnings are for important caveats that don't necessarily stop users from proceeding, but that they should be aware of.
 :::
 :::danger title="Critical Warning"
 ⚠️ **Do not** remove the `remark-directive` plugin from the remark pipeline without also removing the callout directive transformer. Doing so will cause build errors.
 Consequences of removing `remark-directive`:
 - Build failures due to unrecognized directive nodes
 - Broken MDX compilation
 - Lost callout functionality
 :::
 ## Collapsible Content
 Collapsible sections are perfect for hiding optional details that interested readers can expand. They keep the main content clean while providing depth for those who want it.
 <details>
 <summary>Click to expand: Technical Implementation Details</summary>
 The callout system works through a two-stage pipeline:
 1. **`remark-directive`** parses `:::type` syntax and creates directive nodes in the MDX AST
 2. **`callout-directive`** (custom plugin) transforms these nodes into `<Callout>` JSX elements
 This approach is clean because it leverages the existing MDX compilation pipeline without requiring JSX syntax in the source files.
 <details>
 <summary>Even deeper: AST Transformation</summary>
 The transformer uses `unist-util-visit` to find `textDirective` nodes, extracts attributes, and converts them to `mdxJsxFlowElement` nodes with the appropriate props. This nested collapsible demonstrates that the feature supports unlimited nesting depth.
 </details>
 </details>
 ## Mixed Complex Content
 ### Combining Features
 Real-world technical writing rarely uses just one feature at a time. Here's how different elements work together in practice:
 1. You can have **inline code** like `useEffect()` in a list
 2. Followed by a blockquote:
   > "The best code is the code you don't write." — Unknown
 3. And even a small table:
   | Method | Purpose |
   |--------|---------|
   | `useState` | Local state |
   | `useEffect` | Side effects |
 This kind of layered content is exactly what MDX enables — combining the simplicity of Markdown with the expressiveness of JSX.
 ### Keyboard Shortcuts
 Press <kbd>Ctrl</kbd> + <kbd>S</kbd> to save, or use <kbd>Cmd</kbd> + <kbd>S</kbd> on macOS. For navigating the table of contents, use <kbd>Tab</kbd> to move between links and <kbd>Enter</kbd> to activate.
 The `<kbd>` element renders keyboard keys with a distinct visual style, making shortcut documentation clear and accessible.
 ---
 ## Advanced Markdown Patterns
 Beyond the basics, MDX supports several advanced patterns that enhance both the authoring experience and the final output.
 ### Definition Lists Through Blockquotes
 While Markdown doesn't natively support definition lists, you can achieve a similar effect using blockquotes with bold terms:
 > **Remark:** A plugin-based toolchain for processing Markdown with unified.
 >
 > **Rehype:** The HTML equivalent of Remark, operating on HTML-abstract syntax trees.
 >
 > **MDX:** A format that combines Markdown and JSX, enabling rich components within static content.
 ### Horizontal Rules as Section Dividers
 Horizontal rules like the one below help visually separate major sections within long articles, giving readers breathing room between topics:
 ---
 They're subtle but effective for maintaining readability in comprehensive documents.
 ## Performance Considerations
 When building content-heavy sites, performance matters. Here are some best practices:
 1. **Optimize images**: Use modern formats like WebP and include responsive sizes.
 2. **Lazy load content**: Defer non-critical images and heavy components below the fold.
 3. **Cache math rendering**: KaTeX can be expensive; consider server-side rendering for complex equations.
 4. **Minimize custom components**: Each JSX component in MDX adds to the compilation overhead.
 5. **Use static generation**: Pre-render content at build time for the fastest possible delivery.
 ## Closing Thoughts
 This showcase demonstrates the full range of Markdown and MDX features available on this blog. From basic typography to advanced math rendering, from interactive code blocks to styled callouts — the content pipeline supports rich, engaging technical writing.
 The combination of:
 - Clean Markdown syntax for everyday writing
 - Full JSX support for interactive components
 - Syntax-highlighted code blocks with line numbers
 - Beautiful math rendering with KaTeX
 - Distinct callout styles for emphasis
 - Collapsible sections for optional detail
 ...creates a powerful authoring platform that scales from simple blog posts to comprehensive technical documentation.
 Happy writing!