Transform markdown documentation folders into professional Astro-based wikis using refero-design principles (research-first, anti-AI-slop: no default emojis, no 3-column layouts, sections + dividers + media blocks over cards, neutral color system). Use when the user has a folder of .md files and wants to generate a polished wiki/documentation site with dark/light mode support, readable typography, and professional aesthetics. Triggers on requests involving markdown-to-wiki conversion, documentation site generation, Astro wiki creation, or brand wiki themes.
Transform markdown documentation folders into professional Astro-based wikis using refero-design principles (research-first, anti-AI-slop: no default emojis, no 3-column layouts, sections + dividers + media blocks over cards, neutral color system). Use when the user has a folder of .md files and wants to generate a polished wiki/documentation site with dark/light mode support, readable typography, and professional aesthetics. Triggers on requests involving markdown-to-wiki conversion, documentation site generation, Astro wiki creation, or brand wiki themes.
Execution Context
This skill runs AFTER wiki-doc-generator, not as part of the bm launch pipeline.
It converts wiki markdown pages into a glassmorphism Astro site.
Use process-markdown.sh --images <generated-dir> to include visual assets alongside markdown.
Always run init-astro-wiki.sh first to scaffold the Astro project.
Markdown to Astro Wiki Generator
Transform any folder of markdown documentation into a stunning glassmorphism-styled wiki powered by Astro and Bun.
Workflow Overview
Scan - Analyze the markdown folder structure and content
Structure - Generate navigation hierarchy and content collections
Style - Apply iOS26 glassmorphism design system
Build - Create complete Astro project with Bun
Step 1: Scan Documentation
Analyze the user's markdown folder to understand the structure:
# List all markdown files recursively
find /path/to/docs -name "*.md" -type f | head -50
# Check folder depth and organization
find /path/to/docs - d | -20
type
head
Extract from each markdown file:
Title (first # heading or filename)
Description (first paragraph or frontmatter)
Category (parent folder name)
Order (numeric prefix if present, e.g., 01-introduction.md)
Step 2: Initialize Astro Project
Run the initialization script to scaffold the project:
cd /home/claude
./scripts/init-astro-wiki.sh <project-name>
The script creates:
Astro project with Bun
Content collections configuration
Glassmorphism component library
Theme toggle system
Navigation components
Step 3: Process Markdown Files
For each markdown file, create corresponding content:
# User has docs in ~/my-project/docs/# Run the full conversion:# 1. Initialize
./scripts/init-astro-wiki.sh my-wiki
# 2. Process markdown
./scripts/process-markdown.sh ~/my-project/docs ./my-wiki/src/content/docs
# 3. Buildcd my-wiki && bun run build
Design Principles
Depth through Layers - Use z-index, shadows, and blur to create visual hierarchy
Subtle Motion - Smooth transitions (200-300ms) on hover and state changes
Readable Contrast - WCAG AA minimum, prefer AAA for body text
Responsive Glass - Adjust blur and transparency for performance on mobile
System Integration - Respect prefers-color-scheme and prefers-reduced-motion
Resources
scripts/init-astro-wiki.sh - Project scaffolding
scripts/process-markdown.sh - Markdown processing and frontmatter injection
references/glassmorphism-system.md - Complete design system documentation
