Skip to article content

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.

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

ida 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.
filea string - a path to a local file. If file is defined, id/url are not allowed.
urla 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.
titlea 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
filenamea 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.
statica 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:

  1. Build the PDF. For examples of how to build PDFs, see Scientific PDFs. Let’s say the PDF was output to ./mydoc.pdf.
  2. Specify the file path in your page’s metadata. The filepath should point to the location of the built PDF relative to the page.
  - 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.

    - 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, you may do:

  - file:
    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.
  - output: paper.pdf
    template: lapreprint-typst
    id: my-paper
  - file:
    title: Source File
  - id: my-paper
    title: Publication
  - url:
    title: Sample Code
  - url:
    title: More Info
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication