Files
Make local downloads and linked resources easy to discover without interrupting the guide.
<File
src="../assets/quick-reference.txt"
name="Quick reference"
description="Local text file · downloads by default"
/>File turns a local or remote resource into a compact, recognisable download
card. Use it for a template, checklist, sample data set, archive, or reference
document that supports the page without forcing readers to hunt through a
paragraph of links. Without src or href, the same component remains a leaf
item for Tree.
Link to local downloads from the page that needs them
Use a relative src for a file checked into the project. The path is resolved
from the current MDX file, copied to the production build, and downloaded by
default when a reader selects the card.
<File src="./assets/content-template.zip" name="Content template" description="Starter MDX files and example navigation"/>This works well at the end of a quickstart, where a reader may want a complete starter structure after understanding the manual steps. Give the card a human name and say what it contains; a raw file name rarely provides enough context.
Distinguish downloads from external resources
Use href for a regular link URL. External files open in a new tab with a safe
noreferrer relationship, while local files download by default. Set
download={false} for a local PDF or text file that should open in the browser
instead of downloading.
<File
href="https://example.com/brand-guidelines.pdf"
name="Brand guidelines"
description="External PDF · opens in a new tab"
/>Use an external link when another team or service owns the latest file. For a resource that is part of the documentation contract—such as a migration template or a required schema—prefer a versioned local file so it stays in sync with the guide.
Keep downloads purposeful
One well-labelled file card is easier to notice than a large collection of attachments. Put the download near the step that uses it, state the format when it matters, and explain whether readers should edit, upload, or simply read the file after opening it.
Properties
A local relative or remote URL for the resource. It is an alias for
href; use it when the file is part of the current docs source.
A regular destination URL. Use it for externally maintained resources or when the same URL is already used elsewhere as a link.
The visible title of the file card. When omitted, File uses its children or derives a name from the URL.
Supporting metadata shown under the title, such as file contents, format, size, or the action readers should take.
Controls downloading for a local linked file. It defaults to
true; set it to false when a browser-readable
local file should open normally.
A fallback label for a linked File, or the text shown by a tree-style File
when neither src nor href is supplied.