Documents & Folders

Organize your specifications into a logical hierarchy using documents and folders.

Creating Documents

To create a new document:

1. In the file tree, click the New Document button (+ icon) or right-click a folder.
2. Enter a title. SpecDown auto-generates the slug from the title.
3. Click Create. The document opens in the editor immediately.

Via CLI:

specdown new "Authentication Guide"
# Inside a folder:
specdown new "OAuth Flow" --parent guides

Creating Folders

Folders are containers — they hold other documents and folders but have no Markdown content of their own.

To create a folder, click the folder+ icon in the file tree header, or use the CLI:

specdown new "API Reference" --folder

📁 guides/
  📁 api/
    📄 authentication
    📄 endpoints
  📁 tutorials/
    📄 getting-started
📄 changelog

Reordering

Drag-and-drop documents and folders in the file tree to reorder them. The order is preserved in the sort_order field and reflected in the share view.

Within a folder, the sort order is: folders first, then by sort_order, then alphabetically.

Renaming

Double-click a document or folder name in the file tree to rename it inline. Renames work for every kind of item — Markdown documents, HTML documents, and folders.

File extensions are preserved automatically. Renaming my-page.html to landing produces landing.html — you don't have to retype .html. To convert a file's kind (rare), include the new extension in the new name, e.g. landing.md.

Renaming a folder updates the path prefix of every descendant in the same operation, so links inside the project keep resolving without further edits.

Deleting Documents

SpecDown uses soft deletes — deleting a document sets a deleted_at timestamp rather than removing it permanently. This protects you from accidental data loss.

To delete:

• Right-click the document in the file tree → Delete
• Via CLI: specdown rm guides/api/authentication

Project Attachments

In addition to documents and folders, the file tree can include project attachments. These are non-document files that keep their own project path and open in preview mode.

• Use the upload button in the file tree header to import files or folders
• .md, .html, and .htm files become editable documents
• PDFs, images, videos, CSV, and other code/text files become attachments
• Attachments are visible in the same tree and can be referenced from Markdown with [@/path/to/file]

Document Limits