File vs folder

File count does not define content type. Purpose defines type; size and navigation needs define shape.

Shape decision tree

Content item

├── Is it a browsable entity with repeatable fields?
│   └── Data entry
│       └── Example: tools, vendors, people, links
│
├── Is it a reusable bundle with multiple files?
│   └── Kit
│       └── Example: CodeCanyon AI System Kit
│
├── Can it be read as one focused page?
│   └── One file
│       └── Example: guides/connect-vercel-git.md
│
└── Does it need 3+ independently linkable parts?
    └── Folder with index
        ├── index.mdx
        ├── part-1.md
        ├── part-2.md
        └── part-3.md

One file is enough when

• The page answers one question.
• The reader can scan it in one sitting.
• It has fewer than three sections that deserve separate URLs.
• It does not need a separate landing page.

Example:

learn/guides/connect-vercel-git.md

Use a folder when

• The item has three or more child pages.
• The overview page needs to route readers through subtopics.
• Search results should land on specific parts, not one long page.
• The item has reusable diagrams, templates, or examples that need their own pages.

Example:

build/playbooks/setup-new-codecanyon-laravel/
  index.mdx
  01-ai-system.md
  02-code-repo.md
  03-local-dev.md

SOP examples

An SOP can be one file:

build/sops/rotate-api-key.md

Or a folder:

build/sops/production-deploy/
  index.mdx
  preflight.md
  deploy.md
  rollback.md
  verification.md

Both are SOPs. The first is small; the second needs separately linkable parts.

Naming rules

Shape	Rule
One file	Use a descriptive slug: connect-vercel-git.md.
Folder	Use a descriptive folder and an index.mdx.
Kit	Use a folder or downloadable asset; document it with one page.
Data entry	Store in the directory collection or data file for that entity type.