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.

Bonus: Add an API Documentation Link

Any project can expose its external API spec without touching code — add one frontmatter field:

---
title: Custom Ecommerce Backend API
slug: custom-ecommerce-backend-api
github: https://github.com/Abo3baziz/ecommerce
apiDocsUrl: https://codebyahmed.mintlify.site/introduction
---

• apiDocsUrl (alias apiDocs) must be a full https:// URL — invalid URLs fail the build with Invalid apiDocsUrl in <file>.
• When present, an API Documentation button appears in two places — the project header (Source Code · Design Docs · API Documentation · Live Demo, outline with FileCode + ExternalLink, target="_blank") and the Design Docs index header. When absent, no button renders — no empty placeholder.
• The ecommerce project is the first consumer (https://codebyahmed.mintlify.site/introduction); easydownload and others intentionally omit the field.

Where It Shows Up

• Card — "Docs" button (only if docs exist).
• Project page — "Design Docs" beside "Source Code", plus "API Documentation" when apiDocsUrl is set.
• Index — /projects/<slug>/design-docs lists every doc, plus API Documentation in the header when the project declares it.
• 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.