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.

Add a download link¶

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

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.

For example,

article.md

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

Define downloads for all pages

In the above example, the download configuration was defined for a single page (article.md). If you want to add downloads to every page, you can set the download information at the project level:

myst.yml

project:
  ...
  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:

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
---
```

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

Build the PDF. Run the myst build command to build the PDF, e.g.
```
myst build --pdf
```
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.

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

Example GitHub Action configuration to include PDF with GitHub Pages

.github/workflows/deploy.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v3
      - uses: actions/setup-node@v4
        with:
          node-version: 18.x
      
      # Install MyST and PDF dependencies
      - name: Install MyST Markdown
        run: npm install -g mystmd
      - name: Setup Typst
        uses: typst-community/setup-typst@v4
      
      # Build PDF and then HTML
      - name: Build PDF Assets
        run: myst build --pdf
      - name: Build HTML Assets
        run: myst build --html
      
      # Upload to GitHub Pages
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: './_build/html'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

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