l-handle-deep-article

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)...

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