⤵️ Add {download} role (#440)

See jupyter-book/jupyterlab-myst#158, #189

.changeset/five-numbers-invent.md

@@ -0,0 +1,6 @@
+---
+'myst-roles': patch
+'myst-cli': patch
+---
+
+Add download role

docs/cross-references.md

@@ -76,19 +76,19 @@ Cross-referencing content is accomplished with markdown link syntax (`[text](#ta
     : Link to documents using relative links from the markdown.
   - [](./citations.md)
 * - `[](./_toc.yml)`
-    : Link to static files that will be included in your built website.
+    : Link to static files that will be included in your built website. Similar to the [{download}](#download-role) role.
   - [](./_toc.yml)
 ```
 
 % TODO: absolute links
 
-```{seealso}
+:::{seealso} Using roles for referencing
 :class: dropdown
-# Using roles for referencing
-If is also possible to use specific roles to reference content, including ([ref](#ref-role), [numref](#numref-role), [eq](#eq-role) or [doc](#doc-role)), depending on your use-case.
+
+It is also possible to use specific roles to reference content, including ([ref](#ref-role), [numref](#numref-role), [eq](#eq-role) or [doc](#doc-role)), depending on your use-case.
 
 These roles are supported to have compatibility with Sphinx. However, it is recommended to use markdown link syntax for referencing content, as it is more portable, is more concise, and has improved features such as inline formatting in the text links.
-```
+:::
 
 (targeting-headers)=
 
@@ -233,14 +233,13 @@ Please see [this paragraph](#my-paragraph) and [these points](#my-points).
 
 ## Referencing using Roles
 
-```{warning}
-# Coming from Sphinx?
+:::{warning} Coming from Sphinx?
 The following sections are to support users who are coming from using Sphinx as a parsing engine, which has many different ways to reference and label content.
 
 These ways of referencing content are not recommended, as they have certain drawbacks and are not consistent.
 
 See [{name}](#link-references) for ways to use markdown link, `[](#target)` syntax to reference your content.
-```
+:::
 
 (ref-role)=
 
@@ -263,4 +262,7 @@ eq
 doc
 : The `` {doc}`./my-file.md` `` syntax creates a link to the document, which is equivalent to `[](./my-file.md)`.
 
-% TODO: mystjs - doc role (or just leave unhandled until we can do multi doc)
+(download-role)=
+
+download
+: The `` {download}`./my-file.zip` `` syntax creates a download to a document, which is equivalent to `[](./my-file.zip)`.

packages/myst-cli/src/transforms/links.ts

@@ -117,6 +117,7 @@ export class StaticFileTransformer implements LinkTransformer {
     this.session = session;
     this.filePath = filePath;
   }
+
   test(url?: string) {
     if (!url) return false;
     const linkFileWithTarget = fileFromRelativePath(url, this.filePath);

packages/myst-roles/src/download.ts

@@ -0,0 +1,26 @@
+import type { RoleSpec } from 'myst-common';
+import { ParseTypesEnum } from 'myst-common';
+
+const REF_PATTERN = /^(.+?)<([^<>]+)>$/; // e.g. 'Labeled Download <file.zip>'
+
+export const downloadRole: RoleSpec = {
+  name: 'download',
+  body: {
+    type: ParseTypesEnum.string,
+    required: true,
+  },
+  run(data) {
+    const body = data.body as string;
+    const match = REF_PATTERN.exec(body);
+    const [, modified, rawLabel] = match ?? [];
+    const url = rawLabel ?? body;
+    return [
+      {
+        type: 'link',
+        url,
+        children: modified ? [{ type: 'text', value: modified.trim() }] : undefined,
+        static: true, // Indicate that this should be treated as a static download
+      },
+    ];
+  },
+};

packages/myst-roles/src/index.ts

@@ -5,6 +5,7 @@ import { deleteRole } from './delete.js';
 import { mathRole } from './math.js';
 import { refRole } from './reference.js';
 import { docRole } from './doc.js';
+import { downloadRole } from './download.js';
 import { termRole } from './term.js';
 import { siRole } from './si.js';
 import { evalRole } from './inlineExpression.js';
@@ -21,6 +22,7 @@ export const defaultRoles = [
   mathRole,
   refRole,
   docRole,
+  downloadRole,
   termRole,
   siRole,
   evalRole,
@@ -36,6 +38,7 @@ export { deleteRole } from './delete.js';
 export { mathRole } from './math.js';
 export { refRole } from './reference.js';
 export { docRole } from './doc.js';
+export { downloadRole } from './download.js';
 export { termRole } from './term.js';
 export { siRole } from './si.js';
 export { smallcapsRole } from './smallcaps.js';