Skip to content

Clarify download documentation #2597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
choldgraf wants to merge 1 commit into
base: main
Choose a base branch
from
+44 −9
Open

Clarify download documentation #2597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/frontmatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -434,6 +434,10 @@ For usage information, see [](./documents-exports.md).
Downloads allow you to include downloadable files with a MyST website.
They are specified in either:

+++ {"label": "frontmatter-downloads" }

In **project configuration**:

```{code-block} yaml
:filename: myst.yml
project:
Expand All @@ -453,6 +457,8 @@ downloads:
---
```

+++

See [](./website-downloads.md) information about how to use this feature.
Below is a list of all possible downloads configuration.

Expand Down
47 changes: 38 additions & 9 deletions docs/website-downloads.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,48 @@ short_title: Downloads & Static Files
description: Add download links to your website on each page or project
---

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.
You can bundle files with your MyST site for others to download and re-use.
There are two ways to specify downloads with a MyST site.

- 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.
:::{note} Download URLs will changed based on the file content
MyST will generated a _hashed filename_ for any files bundled with your site.
For example: `myfile.[HASH].png`.
This means download URLs will not be persistent if the content changes.

See this issue tracking how to make these URLs stable: https://github.com/jupyter-book/mystmd/issues/1196
:::

## Use the `{download}` role

The {myst:role}`download` role takes a path to a file, and generates a download link from it. The file
They may be defined at the project or the page level.

For example:

::::{grid} 2

```
{download}`references.bib`
```

{download}`references.bib`
::::

(download-link)=
## Add a download link
## Use project or page configuration

There are some special configuration fields to specify files that should be bundled for download with your site. These are:

![](#frontmatter-downloads)

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

![](#table-frontmatter-downloads)

For example,
:::{note} An example download configuration

To add the download to only one page:

```{code-block} yaml
:label: config-page-download
Expand All @@ -30,7 +57,8 @@ downloads:
---
```

:::{tip} Define downloads for all pages
To add the download to all pages in a MyST project:

In [the above example](#config-page-download), 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:

```{code-block} yaml
Expand All @@ -47,8 +75,9 @@ project:

:::


(include-exported-pdf)=
## Include an exported PDF
## How to include an exported PDF with your site

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

Expand Down