|
| 1 | +--- |
| 2 | +title: Downloads |
| 3 | +--- |
| 4 | + |
| 5 | +# Downloads ((tag|VitePress plugin|blue)) |
| 6 | + |
| 7 | +[[readingTime]] |
| 8 | + |
| 9 | +`@binarynoir/vitepress-downloads` turns a folder named `downloads` into downloadable files, linked with a plain relative path. VitePress is built for pages, so a `.sql`, `.zip` or `.xlsx` normally has to be copied into `public/` and linked by an absolute URL. With this plugin the file stays next to the page that uses it. |
| 10 | + |
| 11 | +```txt |
| 12 | +docs/tools/ai/ |
| 13 | + index.md |
| 14 | + downloads/ |
| 15 | + check-access.sql |
| 16 | + template.xlsx |
| 17 | +``` |
| 18 | + |
| 19 | +```md |
| 20 | +[Access check script](./downloads/check-access.sql) |
| 21 | +``` |
| 22 | + |
| 23 | +The file is published at `/tools/ai/downloads/check-access.sql`, and the link downloads it instead of opening a page. It works in `vitepress dev` and `vitepress build`. |
| 24 | + |
| 25 | +## Try it |
| 26 | + |
| 27 | +This page has its own `downloads` folder: `sample.sql` and `sample.md`. |
| 28 | + |
| 29 | +## Install |
| 30 | + |
| 31 | +```sh |
| 32 | +npm install --save-dev @binarynoir/vitepress-downloads |
| 33 | +``` |
| 34 | + |
| 35 | +## Use |
| 36 | + |
| 37 | +```ts |
| 38 | +// .vitepress/config.mts |
| 39 | +import { defineConfig } from 'vitepress'; |
| 40 | +import { withDownloads } from '@binarynoir/vitepress-downloads/vitepress'; |
| 41 | + |
| 42 | +export default withDownloads( |
| 43 | + defineConfig({ |
| 44 | + // ...your config |
| 45 | + }), |
| 46 | +); |
| 47 | +``` |
| 48 | + |
| 49 | +`withDownloads` keeps your existing `srcExclude`, `markdown.config` and `vite.plugins`, so it composes with other wrappers in any order. |
| 50 | + |
| 51 | +## How links work |
| 52 | + |
| 53 | +Links resolve the way any Markdown link does: from the page's own folder, or from the docs root when they start with `/`. A link counts as a download when its target is inside a download folder. Every other link is left to VitePress. |
| 54 | + |
| 55 | +| You write | Result | |
| 56 | +| ----------------------------- | --------------------------------------------------------- | |
| 57 | +| `[x](./downloads/a.sql)` | Download of `a.sql` in the page's own `downloads` folder. | |
| 58 | +| `[x](downloads/a.xlsx)` | The same, without the `./`. | |
| 59 | +| `[x](/guide/downloads/z.zip)` | A file from another section, by path from the docs root. | |
| 60 | +| `[x](./other-page.md)` | Not a download. VitePress handles it as a page link. | |
| 61 | + |
| 62 | +Files of any type work, including `.md`, `.js` and `.json`. Markdown files inside a download folder are never built as pages. |
| 63 | + |
| 64 | +## Options |
| 65 | + |
| 66 | +| Option | Default | Description | |
| 67 | +| ----------- | --------------- | ---------------------------------------------------------------------------------------------------------- | |
| 68 | +| `folders` | `["downloads"]` | Folder name or names to publish. Names, not paths, matched at any depth. `files` is a common second. | |
| 69 | +| `onMissing` | `"warn"` | A link into a download folder with no file behind it: `"warn"`, `"error"` (fails the build) or `"ignore"`. | |
| 70 | + |
| 71 | +```ts |
| 72 | +withDownloads(config, { folders: ['downloads', 'files'], onMissing: 'error' }); |
| 73 | +``` |
| 74 | + |
| 75 | +## Keep downloads out of the sidebar |
| 76 | + |
| 77 | +If the sidebar is generated from the folder tree, a downloadable `notes.md` would show up as a dead sidebar page. With [Auto Sidebar](/plugins/auto-sidebar) and [Auto Navbar](/plugins/auto-navbar), list the folder in an `.exclude` file in the directory that contains it: |
| 78 | + |
| 79 | +```txt |
| 80 | +# docs/tools/ai/.exclude |
| 81 | +downloads/ |
| 82 | +``` |
| 83 | + |
| 84 | +## Good to know |
| 85 | + |
| 86 | +- **Everything in a download folder is public.** Files are copied into the built site as they are. |
| 87 | +- Hidden files such as `.DS_Store`, and `node_modules`, are never published. |
| 88 | +- In dev, downloads are served from disk as attachments, so a `.js` or `.ts` file is not turned into a module. |
| 89 | +- Folder names are case-sensitive: `Downloads` is not `downloads`. |
| 90 | + |
| 91 | +[Source and full README on GitHub](https://github.com/binarynoir/vitepress-downloads) |
0 commit comments