marsultor/public-blog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

content: consolidate starter posts into single comprehensive MDX showcase

Browse Source
This commit is contained in:
kbot
2026-06-03 21:53:07 -05:00
parent 0f516bd23b
commit f8383fb471
4 changed files with 314 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

33
content/posts/designing-with-nextjs.mdx
View File

@@ -1,33 +0,0 @@
---
title: "Designing With Next.js"
date: "2026-05-22"
excerpt: "A short sample note about pairing interface design decisions with static Next.js content."
tags:
- Design
- Next.js
- Web Dev
author: "Starter Content"
coverImage: "/starter-diagram.svg"
---
This sample note gives tag pages another realistic post to list. It is intentionally brief and ready to replace.
![Simple local diagram for a starter design post](/starter-diagram.svg)
## A tiny design checklist
- Keep headings scannable.
- Pair every visual with helpful alt text.
- Use consistent tags so archive pages feel populated.
The same content can support readers and tooling: humans get structure, while static route generation gets predictable params.
```ts title="content-tags.ts" {3}
export const starterTags = [
'Design',
'Next.js',
'Web Dev',
]
```
> Replace this with a real design journal, launch note, or tutorial when you are ready.

33
content/posts/math-notes-for-builders.mdx
View File

@@ -1,33 +0,0 @@
---
title: "Math Notes for Builders"
date: "2026-05-08"
excerpt: "A compact starter post that keeps Math and Code tags populated while checking equation rendering."
tags:
- Math
- Code
- Web Dev
author: "Starter Content"
---
This replaceable note exists to keep the **Math**, **Code**, and **Web Dev** tag pages meaningful during early validation.
## Tiny model
Inline math can express a quick estimate like $n \log n$, while display math can show the full relationship:
$$
T(n) = O(n \log n) + O(k)
$$
## Practical reminder
- Prefer simple explanations before formulas.
- Add runnable code when it clarifies an idea.
- Link back to related posts, such as the [starter showcase](/posts/starter-mdx-showcase/).
```js title="estimate.js" {1,4}
export function estimate(items, constant = 1) {
const n = Math.max(items.length, 1)
return n * Math.log2(n) + constant
}
```

73
content/posts/starter-mdx-showcase.mdx
View File

@@ -1,73 +0,0 @@
---
title: "Starter MDX Showcase"
date: "2026-06-03"
excerpt: "Sample starter content demonstrating math, local images, links, tables, tasks, and code blocks for validating site routes."
tags:
- Design
- Next.js
- Math
- Code
- Web Dev
author: "Starter Content"
coverImage: "/starter-showcase.svg"
---
This is deliberately sample content for Krishna's journal. Replace it with your own writing once the routes, tags, and search experience are validated.
![Abstract gradient card used as a local starter cover](/starter-showcase.svg)
## What this post covers
- A local image from `public/` referenced with an absolute path.
- Links to [Next.js](https://nextjs.org/) and an internal [tag page](/tags/web-dev/).
- GFM tables, task lists, blockquotes, code fences, and math.
> Starter posts should be easy to delete, but rich enough to prove the publishing pipeline works end to end.
## Markdown and GFM examples
| Feature | Purpose | Status |
| --- | --- | --- |
| Tags | Builds static tag pages | Ready |
| Math | Checks KaTeX rendering | Ready |
| Code | Checks syntax highlighting | Ready |
- [x] Confirm route generation has at least one post.
- [x] Confirm spaced tags such as **Web Dev** create usable params.
- [ ] Replace this demo with a real article.
Inline code like `generateStaticParams` should be readable inside a sentence, and inline math such as $E = mc^2$ should render without extra setup.
Display math is useful for longer equations:
$$
\operatorname{score}(post) = \frac{links + images + code}{reading\ time}
$$
## Code with title and highlighted lines
```tsx title="components/example-card.tsx" {2,6-8}
type ExampleCardProps = {
title: string
href: string
}
export function ExampleCard({ title, href }: ExampleCardProps) {
return <a href={href}>{title}</a>
}
```
## Lists, links, and details
1. Draft the article in MDX.
2. Add concrete examples and screenshots.
3. Link to useful references, such as the [MDX docs](https://mdxjs.com/).
<details>
<summary>Why keep demo content obvious?</summary>
<p>Because starter posts are fixtures for validation, not permanent editorial content.</p>
</details>
## Closing note
This post intentionally exercises common authoring features so the owner can validate static post routes, tag pages, and future search indexing with realistic but replaceable content.

314
content/posts/ultimate-mdx-showcase.mdx Normal file
View File

@@ -0,0 +1,314 @@
---
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!