This guide documents the site'sblock trigger system. Wrap Markdown between:::trigger:::tags to render a component without writing HTML.
What this covers:
- How to use all 11 available components
- When to use each component
- Complete examples
- Ways to combine components
Why block syntax
Previously, our system used single-line /trigger/ commands. While simple, they were limited to the "next" node.
Block triggers (:::component:::) fix that limitation. The opening and closing markers support multi-paragraph callouts and nested content.
Design rules
Block-based triggers follow three core principles:
- Explicit Boundaries: Clear start and end markers
- Semantic Meaning: Component names reflect their purpose
- Composition: Components can contain other Markdown elements
Component Reference
1. Metadata Component
Purpose: Define page frontmatter (title, date, category, image)
The metadata component is the foundation of every blog post. It defines essential information that powers your site's SEO, social media previews, and navigation. Think of it as your post's identity card.
Why It Matters:
- SEO Optimization: Search engines use metadata to understand and rank your content
- Social Sharing: Creates beautiful preview cards on Twitter, LinkedIn, Facebook
- Site Navigation: Powers category filters, date sorting, and related posts
- Reader Context: Shows readers what to expect before they start reading
Syntax:
Place this at the very beginning of your markdown file:
\:::\metadata\:::
title: "Your Post Title"
date: "2025-03-01"
description: "A brief description"
category: "Category Name"
image: "/brand/light-favicon.png"
\:::\metadata\:::
Field Breakdown:
| Field | Required | Purpose | Example |
|---|---|---|---|
title |
✅ | Page title, H1, SEO | "Building Scalable APIs" |
date |
✅ | Publication date (YYYY-MM-DD) | "2025-03-01" |
description |
✅ | Meta description, social preview | "Learn to build APIs at scale" |
category |
⚪ | Content categorization | "Backend Engineering" |
image |
⚪ | Social card image, hero image | "/brand/light-favicon.png" |
Real-World Example:
\:::\metadata\:::
title: "React 19: What's New and Why It Matters"
date: "2025-03-15"
description: "A guide to React 19 features including the Compiler, Server Actions, and Suspense patterns."
category: "Frontend Development"
image: "/brand/light-favicon.png"
\:::\metadata\:::
Best Practices:
✅ Do:
- Write compelling titles (50-60 characters)
- Keep descriptions concise but informative (120-160 characters)
- Use descriptive categories (2-4 words)
- Choose high-resolution images (min 1200x630px)
- Use consistent date formatting (YYYY-MM-DD)
- Test social previews with tools like OpenGraph.xyz
❌ Don't:
- Use clickbait titles
- Write vague descriptions
- Skip required fields
- Use low-quality images
- Change category naming conventions mid-project
2. Page Icon
Purpose: Display an emoji icon at the top of the post
The page icon is one emoji shown at the top of the post. Choose one that helps readers recognize the subject at a glance.
Why Use Icons?
- Visual Identity: Instantly recognizable in blog feeds
- Emotional Tone: Conveys mood before reading
- Brand Consistency: Creates a cohesive visual system
- Mobile-Friendly: Looks great on all screen sizes
Syntax:
Place immediately after metadata:
\:::\icon\:::
✍️
\:::\icon\:::
Icon Categories & Recommendations:
- Writing & Content✍️ 📝 📄 📰 ✒️
- Technology & Code💻 ⚙️ 🔧 🖥️ ⌨️
- Design & Creative🎨 ✨ 🖌️ 🎭 🖼️
- Business & Finance💼 📊 💰 📈 🏢
- Learning & Education📚 🧠 🎓 📖 🔬
- Science & Research🔬 🧪 🔭 ⚗️ 🧬
- Performance & Speed⚡ 🚀 ⏱️ 💨 🏎️
- Security & Privacy🔒 🛡️ 🔐 🕵️ 🚨
- Mobile & Apps📱 📲 💾 🔌 📡
- Data & Analytics📊 📈 📉 🗃️ 💾
- AI & Machine Learning🤖 🧠 🎯 🔮 ⚙️
- Communication💬 📢 📣 🗣️ ✉️
Semantic Pairing Guide:
Match your icon to your post's primary focus:
| Post Topic | Recommended Icon | Why |
|---|---|---|
| API Development | 🔌 | Represents connectivity |
| Performance Optimization | ⚡ | Suggests speed |
| Security Practices | 🔒 | Conveys protection |
| Tutorial/How-To | 📚 | Educational context |
| Product Launch | 🚀 | Excitement and launch |
| Personal Reflection | 💭 | Thoughtful and introspective |
| Year in Review | 📅 | Time-based retrospective |
| System Design | 🏗️ | Building/architecture |
| Testing & QA | 🧪 | Experimental and methodical |
| Open Source | 🌐 | Community and accessibility |
Advanced Examples:
\:::\icon\:::
🚀
\:::\icon\:::
Perfect for: Product launches, new features, deployment guides
\:::\icon\:::
🔬
\:::\icon\:::
Perfect for: Research posts, experiments, data analysis
\:::\icon\:::
🎯
\:::\icon\:::
Perfect for: Goal-setting, strategy, focused tutorials
Best Practices:
✅ Do:
- Choose a single emoji that captures your post's essence
- Match icon to content theme (don't use 🎨 for a backend post)
- Use standard emoji (avoid platform-specific ones)
- Test icon rendering across devices
- Create consistency across similar post types
❌ Don't:
- Use multiple emoji (looks cluttered)
- Choose random emoji without meaning
- Use complex emoji combinations (👨💻)
- Overuse trendy emoji inappropriately
- Change icons frequently for the same content type
3. Stat Blocks
Purpose: Display key metrics, statistics, or data points in a grid layout
- Uptime - 99.9%
- Users - 50k+
- Revenue - $1.2M
- Response Time - 45ms avg
- Error Rate - 0.01%
- Daily Active Users - 125K
- API Calls/day - 2.3M
- Product dashboards
- Performance benchmarks
- Business metrics
- Technical specifications
- Feature comparisons
⚠️Breaking Change: Version 3.0 removes deprecated APIs.
Pattern 3: Resource Hub
Combine bookmarks with explanatory text:
Learning Path: Master React
- Official React Documentationreact.dev
- React course (Video)example.com
- Interactive Playgroundcodesandbox.io
- Best Practices Guideexample.com
💡Suggested Order: Start with official docs, then watch the video course, practice in the playground, and finally read the best practices guide.
Pattern 4: Comparison Table
Use stats for side-by-side comparisons:
Framework Comparison:
| Feature | Next.js | Remix |
|---|---|---|
| Routing | File-based | File-based |
| Data Fetching | Server/Client | Server-first |
| Deployment | Vercel/Any | Any |
| Learning | Moderate | Steep |
- Next.jsBest for Vercel hosting
- RemixBest for full-stack control
💡 Both are excellent choices. Choose based on your deployment target and team expertise.
Best Practices Summary
Do's ✅
- Start with metadata on every post
- Use icons to set the tone visually
- Choose callouts based on semantic meaning
- Include context with quotes and bookmarks
- Compose components for rich layouts
- Test rendering before publishing
Don'ts ❌
- Don't overuse callouts (1-3 per post max)
- Don't nest components (not supported)
- Don't forget closing tags (
:::component:::) - Don't use incorrect component names
- Don't skip metadata (breaks SEO)
Component Quick Reference
| Component | Trigger | Target | Best For |
|---|---|---|---|
| Metadata | :::metadata::: |
Key-Value pairs | SEO, page info |
| Page Icon | :::icon::: |
Single Emoji | Visual identity |
| Stat Grid | :::stat::: |
Unordered List | Metrics, data |
| Math Steps | :::math::: |
Unordered List | Calculations |
| Bookmarks | :::bookmarks::: |
Unordered List | External links |
| Info | :::info::: |
Any content | Tips, explanations |
| Success | :::success::: |
Any content | Achievements, wins |
| Warning | :::warning::: |
Any content | Cautions, limitations |
| Error | :::error::: |
Any content | Critical issues |
| Quote | :::quote::: |
Any content | Citations, inspiration |
| Season | :::season::: Title |
Task List | Roadmaps, timelines |
Troubleshooting Common Issues
Issue 1: Component Not Rendering
Problem: Text appears as-is without styling.
Solution: Check for:
Correct component name (case-sensitive)
Both opening and closing tags
No extra spaces in tags
❌ Wrong: ::info::: ✅ Right:
❌ Wrong: ✅ Right:
Issue 2: Broken Layout
Problem: Components overlap or look misaligned.
Solution:
- Ensure blank lines between components
- Don't nest components inside each other
- Use proper list syntax for stat/math/bookmarks
Issue 3: Missing Content
Problem: Content inside component doesn't display.
Solution:
Check that content is between opening and closing tags
Verify markdown syntax inside component
- Ensure list items use proper markdown❌ Wrong: Item 1Value✅ Right:Item 1- Value
Real-World Examples
Example 1: Product Launch Post
\:::\metadata\:::
title: "Launching Our New API"
date: "2025-03-01"
category: "Product"
\:::\metadata\:::
\:::\icon\:::
🚀
\:::\icon\:::
\:::\info\:::
💡 We're excited to announce the release of our v2 API with 10x better performance!
\:::\info\:::
\:::\stat\:::
- **Endpoints** - 50+
- **Uptime SLA** - 99.99%
- **Rate Limit** - 10K req/min
- **Response Time** - <50ms
\:::\stat\:::
\:::\bookmarks\:::
- [API Documentation](https://docs.example.com)
- [Migration Guide](https://example.com/migrate)
- [Changelog](https://example.com/changelog)
\:::\bookmarks\:::
Example 2: Tutorial Post
\:::\metadata\:::
title: "Building a REST API with Node.js"
date: "2025-03-01"
category: "Tutorial"
\:::\metadata\:::
\:::\icon\:::
💻
\:::\icon\:::
\:::\info\:::
💡 This tutorial assumes basic JavaScript knowledge.
\:::\info\:::
[... tutorial content ...]
\:::\warning\:::
⚠️ Don't forget to add `.env` to your `.gitignore` file!
\:::\warning\:::
\:::\success\:::
✅ Congratulations! You've built your first API.
\:::\success\:::
Example 3: Year in Review
\:::\season\::: Q1: Foundations
- [x] Launched v1.0
- [x] Hit 1K users
- [x] Raised seed round
\:::\season\:::
\:::\season\::: Q2: Growth
- [x] 10K users milestone
- [x] Team grew to 12
- [x] First enterprise client
\:::\season\:::
\:::\season\::: Q3: Expansion
- [x] International launch
- [x] Mobile app release
- [x] 50K users
\:::\season\:::
\:::\season\::: Q4: Looking Ahead
- [ ] Series A fundraising
- [ ] 100K users target
- [ ] Platform ecosystem
\:::\season\:::
Component examples
Here is a complete reference of all available components, their syntax, and live previews.
1. Page Icon
Explanation: The page icon sets the visual tone of the post. It appears at the very top of the article.
Code:
\:::\icon\:::
🎨
\:::\icon\:::
Rendered:
2. Stat Grid
Explanation: Display key metrics or data points in a responsive grid layout.
Code:
\:::\stat\:::
- **Users** - 10k+
- **Uptime** - 99.9%
- **Revenue** - $50k
\:::\stat\:::
Rendered:
- Users10k+
- Uptime99.9%
- Revenue$50k
3. Math Steps
Explanation: Show a sequence of calculation steps with the final result automatically highlighted.
Code:
\:::\math\:::
- Revenue = $10,000
- Costs = -$4,000
- **Profit = $6,000**
\:::\math\:::
Rendered:
- Revenue$10,000
- Costs-$4,000
- Profit$6,000
4. Bookmarks
Explanation: Create rich, Notion-style link cards for external resources.
Code:
\:::\bookmarks\:::
- [Documentation](https://docs.example.com)
- [Video Tutorial](https://youtube.com)
- [Source Code](https://github.com)
\:::\bookmarks\:::
Rendered:
5. Info Callout
Explanation: Use for neutral information, tips, or additional context.
Code:
\:::\info\:::
This is an info callout. Use it for helpful tips or additional context.
\:::\info\:::
Rendered:
This is an info callout. Use it for helpful tips or additional context.
6. Success Callout
Explanation: Use for positive outcomes, achievements, or confirmations.
Code:
\:::\success\:::
Great job! You've successfully completed the tutorial.
\:::\success\:::
Rendered:
Great job! You've successfully completed the tutorial.
7. Warning Callout
Explanation: Use for cautions, important notes, or potential issues.
Code:
\:::\warning\:::
Proceed with caution. This action cannot be undone.
\:::\warning\:::
Rendered:
Proceed with caution. This action cannot be undone.
8. Error Callout
Explanation: Use for critical errors, blockers, or security issues.
Code:
\:::\error\:::
Critical error: Database connection failed. Please check your credentials.
\:::\error\:::
Rendered:
Critical error: Database connection failed. Please check your credentials.
9. Quote Block
Explanation: Highlight memorable quotes or citations with a distinct style.
Code:
\:::\quote\:::
"Simplicity is the ultimate sophistication."
Leonardo da Vinci
\:::\quote\:::
Rendered:
"Simplicity is the ultimate sophistication."
Leonardo da Vinci
10. Season Board
Explanation: Plan projects with quarterly or phased timelines.
Code:
\:::\season\::: Q1: Planning
- [x] Research
- [ ] Design
\:::\season\:::
Rendered:
- Research
- Design
Quick reference before publishing
"The secret of change is to focus all of your energy, not on fighting the old, but on building the new."
Socrates
The system includes 11 components:
✅ Metadata for SEO and structure
✅ Icons for visual identity
✅ Stats for data presentation
✅ Math for calculations
✅ Callouts for emphasis (info, success, warning, error)
✅ Bookmarks for resources
✅ Quotes for inspiration
✅ Seasons for planning
Next steps:
- Try each component in a draft
- Combine only the components the post needs
- Preview the result before publishing
If something breaks:
- Check the troubleshooting section above
- Review real-world examples
- Consult the quick reference table