Skip To Article

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 6:Frontmatter download definitions

fielddescription
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.

For example,

article.md
---
downloads:
  - file: ./interesting-photo.png
    title: An interesting photograph
---

Include an exported PDF

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

  1. Create a PDF export target. For example, the following page frontmatter defines a PDF export, gives it the unique identifier my-document-export, and will output the file exports/my-document.pdf:
    article.md
    1
    2
    3
    4
    5
    6
    7
    ---
    exports:
      - format: pdf
        template: lapreprint-typst
        output: exports/my-document.pdf
        id: my-document-export
    ---
  2. Add a download for that export. The id field should match the one defined for your PDF, e.g.
    article.md
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    ---
    exports:
      - format: pdf
        template: lapreprint-typst
        output: exports/my-document.pdf
        id: my-document-export
    downloads:
      - id: my-document-export
        title: A PDF of this document
    ---
  3. Build the PDF. Run the myst build command to build the PDF, e.g.
    myst build --pdf
  4. Build your website. Now that you’ve built the PDF and added frontmatter for the download button, re-building your site will add a new download dropdown linked to the PDF that you’ve exported.

Include exported files with GitHub Pages

If you’re deploying a static site with GitHub pages, then you will need two build steps to add exported PDF files to your website. Ensure your content has the proper PDF export frontmatter, then follow these two steps in your CI.

  1. First, install the PDF build dependencies and build the PDF with myst build --pdf. In the example below, we’ll show how to install Typst with the setup-typst GitHub action.
  2. Second, build the website with myst build --html. Because your PDF has already been generated, your website will now include it.

See below for sample configuration that accomplishes this:

Include a 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
---
MyST MarkdownMyST Markdown
Community-driven tools for the future of technical communication and publication, part of Jupyter.