Downloads, Links and Static Files

Downloads are downloadable files or useful links you want available on your MyST site. They may be defined at the project or the page level.

If you specify project-level downloads: configuration, it will append each item to the source-file download of each page.
If you specify page-level downloads: configuration, it will override project-level configuration as well as page defaults.

Download links configuration¶

Each download link entry has configuration that modifies its behavior. Note that each entry may only specify one of id, file, or url. Descriptions of these fields and other available fields are in the table below from the downloads configuration.

Table 5:Frontmatter download definitions

field	description
`id`	a string - reference to an existing `export` identifier. The referenced export may be defined in a different file. If `id` is defined, `file`/`url` are not allowed.
`file`	a string - a path to a local file. If `file` is defined, `id`/`url` are not allowed.
`url`	a string - either a full URL or a relative URL of a page in your MyST project. If `url` is defined, `id`/`file` are not allowed.
`title`	a string - title of the `downloads` entry. This will show up as text on the link in your MyST site. `title` is recommended for all downloads, but only required for `url` values; files will default to `filename` title
`filename`	a string - name of the file upon download. By default, this will match the original filename. `url` values do no require a `filename`; if provided, the `url` will be treated as a download link rather than page navigation.
`static`	a boolean - this is automatically set to `true` for local files and `false` otherwise. You may also explicitly set this to `false`; this will bypass any attempt to find the file locally and will keep the value for `url` exactly as it is provided.

Include a built PDF¶

If you want to include a PDF of your document with the downloads, take these steps:

Build the PDF. For examples of how to build PDFs, see Scientific PDFs. Let’s say the PDF was output to ./mydoc.pdf.
Specify the file path in your page’s metadata. The filepath should point to the location of the built PDF relative to the page.

article.md

---
downloads:
  - file: ./mydoc.pdf
    title: A PDF of this document
---

An entry for this PDF will now show up in your page’s downloads dropdown. If you do not specify the output location of your export we recommend that you refer to it by an ID, rather than linking to the ./_build/exports folder, as these may change depending on your exports list. See below for an example.

Specify a download for all pages of a MyST site¶

If you’d like a download link to show up for all pages of a MyST site, use configuration at the myst.yml level. For example, let’s say you used typst to generate a PDF of all documents in your MyST site, called mybook.pdf.

myst.yml

project:
  downloads:
    - file: mybook.pdf
      title: A PDF of this book

Include the raw source file¶

You may include the raw source of a file as a download by referencing the file itself in the download frontmatter. For example inside file index.md, you may do:

downloads:
  - file: index.md
    title: Source File

Include several downloads at once¶

The following example has several downloads: the source file, as above, an exported pdf, a remote file, and a link to another website. In addition, when you specify downloads:, it will over-ride the default download behavior (which is to link to the source file of the current page). This example manually includes a download to the source file to re-enable this.

index.md

---
exports:
  - output: paper.pdf
    template: lapreprint-typst
    id: my-paper
downloads:
  - file: index.md
    title: Source File
  - id: my-paper
    title: Publication
  - url: https://example.com/files/script.py
    filename: script.py
    title: Sample Code
  - url: https://example.com/more-info
    title: More Info
---