By name: l-handle-deep-article description: >- Create or convert CSS best-practices articles into "deep articles" with sub-pages in the zcss Astro site. Use when: (1) An article topic has enough depth to warrant "see more" reference sub-pages, (2) Converting a flat .mdx article into a category with index + child pages, (3) Adding deep reference content to an existing article, (4) User says 'deep article', 'add sub-pages', 'expand article', or 'add reference pages'. user-invocable: true argument-hint: "[article path or topic name]"
Deep Article Handler
Convert a flat .mdx article into a folder with index.mdx + sub-pages when the topic has enough depth.
When to Use
Use when a topic has:
- Reference tables or catalogs too large for inline
- Multiple distinct sub-patterns each deserving focused demos
- Cheat sheet material users would browse independently
- 10+ real-world recipes (card patterns, form patterns, animation recipes)
Do not use for topics that fit in a single page with 4-5 demos.
Conversion Steps
1. Create folder, move main article
cd src/content/docs/<category>/
mkdir my-topic
mv my-topic.mdx my-topic/index.mdx
2. Update index.mdx frontmatter
Add a "Deep Dive" section at bottom:
## Deep Dive
- [Sub-page Title](./sub-page-1) - Brief description
- [Sub-page Title](./sub-page-2) - Brief description
3. Create sub-pages
Each sub-page: standalone .mdx with sidebar_position, CssPreview demos, focused on one aspect.
---
sidebar_position: 1
---
import CssPreview from '@/components/CssPreview';
# Sub-page Title
(CssPreview demos and content)
Conventions
- Main article keeps Problem/Solution/Demo structure
- Sub-pages can be reference-oriented (tables, catalogs, recipes)
- Follow all CSS/demo conventions from
CLAUDE.md - File naming: kebab-case
- After conversion, regenerate css-wisdom index:
pnpm run generate:css-wisdom