Quick Start

Get your first SpecDown project running in under 5 minutes. No credit card required for the Free plan.

Step 1: Create an Account

Go to app.specdown.app/signup and create a free account. You can sign up with:

• GitHub OAuth — recommended if you plan to use Git sync
• GitLab OAuth — same as above for GitLab users
• Email / password — traditional signup

Step 2: Create a Project

After logging in you'll land on the Dashboard. Click New Project in the top-right corner.

1. Name — Give your project a descriptive name, e.g. Payment Service SRS.
2. Description (optional) — Add a short description for context.
3. Git Repository (optional, Pro) — Paste the URL of your GitHub or GitLab repository to enable automatic sync.
4. Click Create Project.

You'll be redirected to the project workspace — an empty editor ready for your first document.

Step 3: Create Your First Document

In the left file tree, click the + button and select:

• New Document — creates a Markdown file
• New Folder — creates a folder to organise documents

Name your document (e.g. overview) and it will open in the editor. The slug is auto-derived from the name. You can rename it later.

Step 4: Write Your Spec

Start writing in the left editor pane. The right pane shows a live preview, updated as you type. Try pasting this starter template:

# Payment Service — Overview

## Purpose

This document describes the requirements for the payment processing
subsystem of our platform.

## Scope

- Accepting credit card payments via Stripe
- Handling refunds and disputes
- Generating monthly invoices

## Architecture

```mermaid
flowchart LR
  Client --> API
  API --> PaymentService
  PaymentService --> Stripe
  PaymentService --> DB[(Database)]
```

## Key Requirements

| ID | Requirement | Priority |
|----|-------------|----------|
| R1 | Process payments in < 3s | High |
| R2 | Store no raw card data | Critical |
| R3 | Send email receipt on success | Medium |

Step 5: Preview Your Document

The live preview pane renders your Markdown in real time, including:

• Mermaid diagrams (flowcharts, sequence diagrams, ER diagrams, etc.)
• Tables with proper formatting
• Syntax-highlighted code blocks
• Images uploaded to Cloudflare R2

You can toggle preview mode using the toolbar buttons: Edit Only, Split View, or Preview Only.

Step 6: Share Your Document

To share with a stakeholder who doesn't have a SpecDown account:

1. Open the document and click the Share button in the toolbar.
2. Click Create Share Link.
3. Copy the link and send it. The recipient sees a clean read-only view of your document with full Mermaid diagram rendering.

Step 7: Invite Your Team

Go to Project Settings → Members and click Invite Member. Enter their email address and assign a role:

• Admin — Can manage members and project settings
• Editor — Can create, edit, and delete documents
• Viewer — Read-only access

The invitee receives an email with a link to join the project. They'll need a SpecDown account (free).

What's Next?

You're all set! Here are some recommended next steps:

• Connect Git Sync to keep your specs in version control alongside your code
• Set up the MCP Server so your AI assistant can read your specs
• Learn Mermaid Diagrams for architecture and flow documentation
• Install the CLI for terminal-based spec management
• Upgrade to Pro for Git sync, MCP, and unlimited documents