How to Use

Overview

Design Docs let you attach one or more documents to any portfolio project. A project card shows a Design Docs button only when docs exist. Clicking it opens an index, then each document.

Quick Start

1. Create the folder

content/design-docs/<your-project-slug>/

Your slug is the slug field in projects/<folder>/<file>.md. For this portfolio it is portfolio.

2. Add meta.yaml

designDocs:
  - id: how-to-use
    title: How to Use
    description: Add design docs to any project in two minutes.
    type: local
    source: how-to-use.mdx

  - id: architecture
    title: Architecture
    description: How the feature works under the hood.
    type: local
    source: architecture.mdx

3. Add the MDX files

Each local document is a plain .mdx file next to meta.yaml. You can use Markdown, tables, code, callouts, and Mermaid — same as project pages.

## My Doc

Hello world.

<Mermaid>
{`flowchart LR
    A --> B
`}
</Mermaid>

> [!info] Note
> Callouts work the same as elsewhere.

Or link to Notion:

- id: api
  title: API Design
  type: notion
  source: https://www.notion.so/your-page-id

No scraping, no iframe — the index just links out to Notion in a new tab.

Where It Shows Up

• Card — "Docs" button (only if docs exist).
• Project page — "Design Docs" beside "Source Code".
• Index — /projects/<slug>/design-docs lists every doc.
• Local doc — /projects/<slug>/design-docs/<id> renders MDX with back links.

You can have 1 doc, 3 docs, or 10 — no hard limit, no pagination needed yet.

Example

For this portfolio:

content/design-docs/portfolio/
├── meta.yaml
├── how-to-use.mdx      ← you are here
└── architecture.mdx

Add, commit, push — the next build picks it up automatically.