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,
---
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 fileexports/my-document.pdf
:article.md1 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.md1 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 thesetup-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
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.
---
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
---