create-specment

English | 日本語

Demo: https://plenarc.github.io/specment/

1. 'specification' + 'document' => Specment
2. A site generation tool specializing in creating specification documents based on Docusaurus

Overview

create-specment is a CLI tool that easily generates Docusaurus projects specialized for specification documentation. It provides Storybook-like ease of use and create-better-t-stack-like interactive setup, integrating all the features needed for specification documentation creation.

Features

1. 🚀 Interactive Setup: Generate projects by simply answering questions
2. 📋 5 Specialized Templates: Choose optimal templates based on your use case
3. 🔧 Feature Selection: Select PlantUML, Redoc, search, multilingual support, and more
4. 📝 Variable Substitution: Automatically replace project names and author information
5. 🎨 Docusaurus Compatible: Fully compatible with the existing Docusaurus ecosystem

Installation Guide

Prerequisites

The following software must be installed:

1. WSL (for Windows environments)

   1. For Windows environments, we strongly recommend using Windows Subsystem for Linux (WSL)
   2. Ubuntu 22.04 LTS or higher is recommended

   # Install WSL (run in Windows PowerShell with administrator privileges)
   wsl --install

2. mise (development environment management tool)

   1. Linux/macOS/WSL

      curl https://mise.run | sh
      
      # Update shell configuration
      echo 'eval "$(mise activate bash)"' >> ~/.bashrc
      source ~/.bashrc

   2. brew

      brew install mise

   3. Version check

      mise --version

3. Node.js (LTS or higher recommended, installation via mise recommended)

   # Install Node.js using mise
   mise install node@lts
   mise use node@lts
   
   # Check version
   node --version

4. ni (package manager unification tool)

   # Install ni using mise
   mise use npm:@antfu/ni@latest
   
   # Check version
   ni --version

Installation Methods

1. For details on each option, see Option Details

Method 1: Using ni (Recommended)

# Create project using ni (interactive setup will start)
nlx create-specment@latest

After execution, the following options will be displayed, so select the necessary documents and features:

◆  Please select display language / 表示言語を選択してください:
│  ● English
│  ○ 日本語
└

┌  🚀 Welcome to create-specment!
Creating a new Docusaurus-based specification documentation project...
│
◆  Enter folder name (project name):
│  _
└

◆  Which templates would you like to use? (Multiple selection)
│  ◻ Project Analysis
│  ◻ Requirements Specification
│  ◻ External Design
│  ◻ Internal Design
│  ◻ API (Using Redocusaurus)
└

◆  Which additional features would you like to include?
│  ◻ PlantUML
│  ◻ Mermaid
└

Once creation is complete, change to the folder and start in development mode after installation:

cd <folder-name> && ni && nr start

Method 2: Using npx

# Start setup
npx create-specment@latest

1. For option details, see Method 1

Interactive Setup

When you run create-specment, the following options will be displayed sequentially:

1. Display Language Selection

◆ Please select display language / 表示言語を選択してください:
│ ● English
│ ○ 日本語

1. Select the display language for the interface
2. Subsequent questions will be displayed in the selected language

2. Project Name Input

◆ Enter folder name (project name):
│ _

1. Enter the folder name for the project to be created
2. This name will become the project directory name

3. Template Selection (Multiple selection possible)

◆ Which templates would you like to use? (Multiple selection)
│ ◻ Project Analysis (Provides structure for understanding project overview)
│ ◻ Requirements Specification
│ ◻ External Design
│ ◻ Internal Design
│ ◻ API (Using Redocusaurus)

1. Multiple templates can be selected simultaneously
2. Each template is generated as an independent section
3. At least one template must be selected

Project Analysis

Project overview and analysis template. Provides structure for understanding the overall picture of the project.

Use Cases:

1. Project proposals
2. Current state analysis reports
3. SWOT analysis documents

Requirements Specification

Requirements specification template. Allows systematic organization of functional and non-functional requirements.

Use Cases:

1. System requirements specifications
2. Functional specifications
3. EARS format requirement descriptions

External Design

External design specification template. Specialized for interface design with external systems.

Use Cases:

1. System architecture design documents
2. API design documents
3. UI/UX design documents

Internal Design

Internal design specification template. Specialized for detailed internal system design and algorithms.

Use Cases:

1. Detailed design documents
2. Database design documents
3. Algorithm specifications

API

1. Using Redocusaurus, you can display YAML format files written in OpenAPI specifications

4. Additional Feature Selection

◆ Which additional features would you like to include?
│ ◻ PlantUML (PlantUML diagram integration (UML diagrams and flowcharts))
│ ◻ Mermaid

1. PlantUML: Adds functionality to create UML diagrams and flowcharts
2. Mermaid: Adds functionality to create diagrams within Markdown
3. Both can be selected

PlantUML

1. You can use PlantUML for UML diagrams and sequence diagrams
2. Uses the Docusaurus theme create-specment
   1. ※ Please refer to the README at the link for usage and precautions

Mermaid

1. Uses the Docusaurus theme theme-mermaid

Multilingual Support

TBD: Plans to support document creation in multiple languages (if requested)

Command Line Options

create-specment [project-name] [options]

Arguments:
  project-name          Folder name for the project to be created (optional)
                        When specified: Skip folder name input

Options:
  -t, --template <template>  Template to use (project-analysis|requirements|external-design|internal-design|api-spec)
  --skip-install        Skip dependency installation
  --verbose             Show detailed logs
  -h, --help           Show help
  -V, --version        Show version

Usage Examples

# Complete interactive setup (all options will be displayed)
create-specment

# Specify folder name and interactive setup (skip folder name input)
create-specment my-docs

# Completely non-interactive (skip folder name and template selection)
create-specment my-docs --template requirements

# Specify template only (folder name input will be displayed)
create-specment --template api-spec

Troubleshooting

Common Issues

1. Node.js Version Error

Error: Node.js version 20.0 or higher is required

Solution:

# Check Node.js version
node --version

# Update Node.js using mise
mise install node@latest
mise use node@latest

2. Package Installation Error

Error: Failed to install dependencies

Solution:

# Clear cache
ni clean
# Or manually clear
npm cache clean --force

# Reinstall
ni

3. Port Conflict Error

Error: Port 3000 is already in use

Solution:

# Specify a different port
nr start -- --port 3001

Notes for Windows Environment

1. Strongly recommend using WSL
   1. For Windows environments, we strongly recommend using WSL (Windows Subsystem for Linux)
   2. Operation in PowerShell or Command Prompt is not guaranteed
   3. Ubuntu 22.04 LTS or higher is recommended
2. Unified Development Environment
   1. The combination of mise + ni minimizes environment differences
   2. Running as a Linux environment within WSL provides an experience equivalent to macOS/Linux

License

MIT License - See the LICENSE file for details.

Contributing

We welcome contributions to the project! See CONTRIBUTING.md for details.

Support

1. 🐛 Bug Reports: GitHub Issues
2. 💡 Feature Requests: GitHub Discussions
3. 📖 Documentation: Official Documentation

関連プロジェクト

1. Docusaurus - Static site generator
2. mise - Development environment management tool
3. ni - Package manager unification tool
4. PlantUML - UML diagram creation tool
5. Redoc - OpenAPI specification display tool