Two ways to use a file in your docs. Pick per asset — they mix freely on the same page:
Repo public/ folder
Commit the file next to your docs. Versioned with your content, no third-party dependency, served from your docs domain.
External URL
Reference any https:// URL — your CDN, S3 bucket, or an existing asset host. Nothing to commit.
Repo public/ folder
Put files in a public/ folder next to your content root and reference them with a root-relative path:
your-repo/
├── docs/ ← your MDX content
├── public/ ← static assets live here
│ ├── logo/
│ │ ├── light.svg
│ │ └── dark.svg
│ └── images/
│ ├── setup-flow.mp4
│ └── dashboard.png
└── nookdocs.config.json<Image src="/images/dashboard.png" alt="Dashboard overview" />
<Video src="/images/setup-flow.mp4" poster="/images/setup-flow-poster.png" loop />
[Download the SDK reference](/files/sdk-reference.pdf)Your logo and favicon in nookdocs.config.json resolve from the same folder.
In a monorepo where your docs live under a subdirectory (content root docs), the public/ folder sits inside that subdirectory: docs/public/…. The URL paths in MDX stay the same.
How serving works
Assets are read from your connected GitHub repo at request time and cached for 5 minutes — pushing a new file makes it available immediately, no rebuild needed.
Served from your docs domain (
docs.example.com/images/…), so there are no cross-origin issues.Files up to 100 MB are supported, but keep web assets small — videos under ~2.5 MB, images under ~500 KB. Large files slow the first uncached request.
Supported file types
Images (svg png jpg webp gif ico avif), media (mp4 webm), documents (pdf txt md json yaml), fonts (woff woff2 ttf otf), and code (css js).
External URLs
Anywhere an asset path is accepted, a full URL works too:
<Image src="https://cdn.acme.com/screenshots/dashboard.png" alt="Dashboard" />
<Video src="https://assets.acme.com/demos/onboarding.mp4" loop />Use external URLs when the asset already lives on your CDN, is shared across multiple sites, or is too large to belong in a git repo.
External assets load from a different origin — if your docs readers are behind a strict corporate proxy or the third-party host goes down, those assets break while repo-hosted ones keep working. For anything load-bearing (logo, key diagrams), prefer the repo public/ folder.
Choosing between them
Repo public/ | External URL | |
| Versioned with docs content | ✓ — rolls back with git | ✗ |
| Survives third-party outages | ✓ | ✗ |
| Good for very large files (>100 MB) | ✗ | ✓ |
| Needs a commit to update | ✓ | ✗ — swap at the source |
| Same-origin (no CORS concerns) | ✓ | depends on host |