Skip to content

Latest commit

 

History

History
272 lines (197 loc) · 6.74 KB

README.md

File metadata and controls

272 lines (197 loc) · 6.74 KB

Docsify Documentation Generator Skill

A powerful Claude Code skill that helps users quickly generate, configure, and manage Docsify documentation projects with built-in version management to prevent breaking changes.

🎯 What This Skill Does

This skill provides an easy way to:

  • Initialize new Docsify documentation projects with theme selection
  • Generate documentation from source code and Markdown files
  • Manage versions with specific major versions (@4, @5) to avoid breaking changes
  • Preview documentation locally with hot reload

✨ Key Features

  • ✅ One-command project initialization with interactive setup
  • ✅ Version-specific installation support (@4, @5, or exact versions)
  • ✅ Automatic documentation structure generation with theme selection
  • ✅ Documentation generation from source code
  • ✅ Local development server with hot reload
  • ✅ Breaking change prevention with version pinning
  • ✅ Helper prompts for user guidance

🚀 Quick Start

1. Install Dependencies

Ensure Node.js and docsify-cli are installed on your system:

# Install Node.js from https://nodejs.org/ (v12 or higher)
# Install docsify-cli globally
npm install -g docsify-cli@4

2. Create a New Project

# With stable v4 (recommended)
/docsify init --name my-docs --version @4

# Or with latest v5
/docsify init --name my-docs --version @5

3. Preview Your Docs

/docsify serve

Visit http://localhost:3000 in your browser to see your documentation!

📋 Available Commands

Command Purpose
/docsify init Initialize a new Docsify project with default structure
/docsify generate Generate documentation from source code and Markdown files
/docsify serve Start local development server for preview

For detailed command documentation, options, and examples, see .claude/skills/docsify.md

📁 Skill Structure

docsify-skill/
├── README.md              # This file
└── SKILL.md              # Main skill definition with command details

🔒 Version Management (Important!)

This skill helps you avoid breaking changes by supporting specific major versions:

Why Version Management Matters

  • Breaking Changes: Major versions often introduce breaking changes
  • Consistency: Keep your team using the same version
  • Predictability: Know exactly what version is installed
  • Safety: Test upgrades before applying them

Using Specific Versions

# Install stable v4 (recommended for existing projects)
/docsify install-deps --version @4

# Install latest v5 (new features, possible breaking changes)
/docsify install-deps --version @5

# Initialize with specific version
/docsify init --name my-docs --version @4

# Install exact version
/docsify install-deps --version @4.13.1

📚 Documentation

  • SKILL.md - Complete command reference, options, and best practices

🛠️ Prerequisites

Before using this skill, ensure you have:

  1. Node.js (v12 or higher)

  2. npm (comes with Node.js)

    • Check: npm --version

  3. docsify-cli

    npm install -g docsify-cli@4  # Or @5 for latest

For detailed installation instructions, see the "Prerequisites & Installation" section in SKILL.md

💡 Common Workflows

Basic Documentation Project

# 1. Initialize project with v4
/docsify init --name my-docs --version @4

# 2. Preview locally
/docsify serve

# 3. Edit markdown files in my-docs/docs/
# 4. Commit and deploy docs folder to hosting

Generate Documentation from Source Code

# 1. Initialize project
/docsify init --name api-docs --version @4

# 2. Generate docs from source code
/docsify generate --source ./src --output ./api-docs/docs

# 3. Preview locally
/docsify serve

# 4. Deploy docs folder

Upgrade Major Version

# 1. Check current version
npm list docsify-cli

# 2. Install new version globally
npm install -g docsify-cli@5

# 3. Test with serve command
/docsify serve

# 4. If successful, commit changes. If issues, rollback to @4
npm install -g docsify-cli@4

🎓 Best Practices

Documentation Organization

  • Use clear, hierarchical structure
  • Keep consistent naming conventions
  • Include a comprehensive README
  • Organize navigation logically

Version Management

  • Lock major versions in package.json
  • Test before upgrading major versions
  • Document version usage in your project
  • Communicate changes to your team
  • Review breaking changes before updating

Deployment

  • Always test locally first
  • Build and verify before deployment
  • Keep version history in git
  • Maintain backward compatibility during transitions

📖 External Resources

🐛 Troubleshooting

Command Not Found

# Make sure docsify-cli is installed globally
npm install -g docsify-cli@4

# Verify installation
docsify --version

Version Conflicts

# Check installed version
npm list -g docsify-cli

# Reinstall specific version
npm install -g docsify-cli@4

Port Already in Use

# Use different port
/docsify serve --port 3001

📝 Usage Examples

Example 1: Basic Project Setup

# Create stable documentation site
/docsify init --name api-docs --version @4
cd api-docs
/docsify serve

# Then edit files in the docs/ folder and reload browser

Example 2: Generate from Source Code

# Initialize project
/docsify init --name technical-docs --version @4

# Generate docs from source code
/docsify generate --source ./my-project/src --output ./technical-docs/docs

# Preview
/docsify serve

Example 3: Documentation Site Workflow

# 1. Initialize
/docsify init --name my-project-docs --version @4

# 2. Generate from source code
/docsify generate --source ./src --output ./my-project-docs/docs

# 3. Preview locally
/docsify serve

# 4. Edit markdown files in my-project-docs/docs/
# 5. Deploy my-project-docs folder to GitHub Pages, Netlify, or Vercel

🤝 Contributing

To extend or modify this skill:

  1. Edit SKILL.md for command definitions
  2. Update README.md for documentation changes
  3. Test all commands locally before committing
  4. Keep version management guidelines updated

📄 License

This skill is provided as-is for use with Claude Code Skill. LICENSE

❓ Support

For issues or questions:

  • Review the command documentation in SKILL.md
  • Visit Docsify official docs for Docsify-specific questions

Happy documenting! 📚