📖 Add dedicated exports and downloads pages (#1064)

Co-authored-by: Rowan Cockett <[email protected]>

docs/_toc.yml

@@ -41,11 +41,13 @@ parts:
       - file: accessibility-and-performance
       # - file: search
       - file: analytics
+      - file: website-downloads
       - file: deployment
       - file: website-templates
       # - file: publishing
   - caption: Documents
     chapters:
+      - file: documents-exports
       - file: creating-pdf-documents
       - file: creating-word-documents
       - file: creating-jats-xml

docs/creating-pdf-documents.md

@@ -24,7 +24,8 @@ To create a new `pdf` export type for your MyST document, in your document front
 
 (export-frontmatter-pdf)=
 
-```yaml
+```{code-block} yaml
+:filename: article.md
 ---
 title: My PDF
 exports:
@@ -92,11 +93,12 @@ Ensure that you download a full distribution with appropriate libraries installe
 
 ## Rendering PDFs with Typst
 
-MyST also provides an option to build PDFs with [Typst](https://typst.app/). Typst is a markup-based typesetting language. Compared to $\LaTeX$, syntax is streamlined and consistent, and compile time is significantly faster. To render Typst PDFs locally, you must install the [Typst CLI](https://github.com/typst/typst).
+MyST also provides an option to build PDFs with [Typst](https://typst.app). Typst is a markup-based typesetting language. Compared to $\LaTeX$, syntax is streamlined and consistent, and compile time is significantly faster. To render Typst PDFs locally, you must install the [Typst CLI](https://github.com/typst/typst).
 
 To add Typst to your export targets, add `format: typst` and select a Typst template. These templates use the same [MyST templating library](myst:jtex) as $\LaTeX$ templates to support document [frontmatter](./frontmatter.md).
 
-```yaml
+```{code-block} yaml
+:filename: article.md
 ---
 title: My PDF
 exports:
@@ -148,21 +150,19 @@ There are two ways to provide information to a template, through `parts` and `op
 
 ## Template `parts`
 
-The `parts` of a template are things like `abstract`, `acknowledgments` or `data_availability`, they are usually written pieces of a document, but are placed specifically in a template. For example, an abstract usually has a place in templates, with a box or other typographic choices applied. These parts can be marked as `required`, and will raise error in the PDF export process, however, myst will always try to complete the build.
-
-A `part` of a template is defined using metadata on a MyST [block](./blocks.md):
+The `parts` of a template are things like `abstract`, `acknowledgments` or `data_availability`, see [](./document-parts.md) for more information. These parts are usually written pieces of a document, but are placed specifically in a template. For example, an abstract usually has a place in templates, with a box or other typographic choices applied. These parts can be marked as `required`, and will raise error in the PDF export process, however, myst will always try to complete the build.
 
-```markdown
-+++ { "part": "abstract" }
+A `part` of a template can be defined using the [page frontmatter](#parts:frontmatter) or [metadata on a block](#parts:blocks). An example of using the frontmatter is:
 
-MyST (Markedly Structured Text) is designed to create publication-quality documents
-written entirely in Markdown. The markup and publishing build system is fantastic,
-MyST seamlessly exports to any PDF template, while collecting metadata to make your
-writing process as easy as possible.
-
-+++
-
-# Introduction
+```{code-block} yaml
+:filename: article.md
+---
+abstract: |
+  MyST (Markedly Structured Text) is designed to create publication-quality documents
+  written entirely in Markdown. The markup and publishing build system is fantastic,
+  MyST seamlessly exports to any PDF template, while collecting metadata to make your
+  writing process as easy as possible.
+---
 ```
 
 ### Template `options`
@@ -172,6 +172,7 @@ Template authors should choose to use [standard frontmatter](./frontmatter.md) p
 ```{code-block} yaml
 :linenos:
 :emphasize-lines: 7
+:filename: article.md
 ---
 title: My PDF
 exports:
@@ -191,6 +192,7 @@ The export list can also point to local templates, for $\LaTeX$ these are built
 To make use of the template locally, validate it using `jtex check` and then point to the template folder in your export:
 
 ```{code-block} yaml
+:filename: article.md
 :linenos:
 :emphasize-lines: 5
 :caption: The template can be a path to a `jtex` template, which contains a `template.yml` and `template.tex` as well as any other `cls` or `def` files.
@@ -217,7 +219,8 @@ Sometimes you may want to combine multiple MyST documents into a single export,
 
 For perform a multi-article export, add multiple `articles` to the export frontmatter:
 
-```yaml
+```{code-block} yaml
+:filename: article.md
 ---
 title: My PDF
 exports:
@@ -234,7 +237,8 @@ exports:
 
 As an alternative to listing articles in MyST frontmatter, you may specify a table of contents using the [Jupyter Book format](#toc-format):
 
-```yaml
+```{code-block} yaml
+:filename: article.md
 ---
 title: My PDF
 exports:
@@ -251,7 +255,8 @@ By default if no `articles` are given, exports defined in page frontmatter will
 
 Export frontmatter may differ from page or project frontmatter. For example, you may with to give your export its own title, which does not match the project title. To do so, add the alternative frontmatter to your export:
 
-```yaml
+```{code-block} yaml
+:filename: article.md
 ---
 title: My Interactive Research!
 exports:
@@ -265,7 +270,8 @@ You may redefine [any frontmatter fields](./frontmatter.md). These redefined fie
 
 Further, for [](#multi-article-exports), you may redefine frontmatter for every specific page. To do so, you must use a list of article objects (as opposed to a `_toc.yml` file or a list of article names):
 
-```yaml
+```{code-block} yaml
+:filename: article.md
 ---
 title: My PDF
 exports:

docs/document-parts.md

@@ -7,6 +7,8 @@ Document parts allow you to add metadata to your documents with specific compone
 
 There are three ways that you can define parts of a document: (1) in your page frontmatter; (2) implicitly using a section heading; and (3) on a block using a `part` or `tag` annotation. These are all based on a part name, which is case insensitive.
 
+(parts:frontmatter)=
+
 ## Parts in Frontmatter
 
 On any page, you can add a part to your document directly in the frontmatter, for example, the `abstract`:
@@ -65,6 +67,8 @@ parts:
 
 The advantage of this method is that the content is not rendered in your document.
 
+(parts:implicit)=
+
 ## Implicit Parts using a Title
 
 If you are rendering your project in other places, it can be helpful to leave these sections directly in the document.
@@ -78,6 +82,8 @@ This is my abstract!
 
 Note that frontmatter parts and explicitly tagged cells/blocks will take precedence over this method. Themes may choose to only pick up a subset of implicit parts, for example, only an `Abstract` and not `Summary` as summary section can be used in other contexts.
 
+(parts:blocks)=
+
 ## In a Jupyter Notebook cells and blocks
 
 When using a Jupyter Notebook, you can add a `tag` to the cell with the part name, if multiple cells share that tag, they will be extracted and merged. This can also be represented in a [block](./blocks.md):

docs/documents-exports.md

@@ -0,0 +1,58 @@
+---
+title: Exporting documents
+description: Create an export for PDF, LaTeX, Typst, Docx, or JATS in your page or project frontmatter, and use `myst build` to build the export.
+---
+
+You may define desired static exports in page or project frontmatter. In the export object, you may specify a `filename`, `format`, and/or `template`, as well as the article(s) you wish to include in your export. You may also provide any additional options required by your template in the export object.
+
+## Types of documents you can export
+
+Below are supported export types and links to documentation for further reading:
+
+```{list-table} Frontmatter Export Formats
+:header-rows: 1
+:name: table-export-docs
+- * Export type
+  * Learn more
+- * `pdf`
+  * [](./creating-pdf-documents.md)
+- * `tex`
+  * [](./creating-pdf-documents.md)
+- * `typst`
+  * [](./creating-pdf-documents.md)
+- * `JATS`
+  * [](./creating-jats-xml.md)
+- * `Microsoft Word`
+  * [](./creating-word-documents.md)
+```
+
+```{seealso} The MyST templating engine drives document exports
+You can also explore the [MyST templating](myst:jtex) documentation for a deeper dive into defining templates.
+```
+
+## Building Exports
+
+After defining `exports` in your frontmatter, you may build them with the `myst build` command, by default this only builds the site.
+You can configure the CLI command in a number of ways:
+
+`myst build --all`
+: Build all exports in the project
+
+`myst build --pdf --docx`
+: Build `pdf` (LaTeX or Typst) exports and `docx` in the project
+
+`myst build my-paper.md`
+: Build all exports in a specific page
+
+`myst build my-paper.md --pdf`
+: Build all `pdf` exports in a specific page
+
+## Export Configuration
+
+The following table shows the available properties for each export. You must define at least one of `format`, `output`, or `template` for MyST to be able to perform your output. You may also specify a string instead of a full export object; this string will be inferred to be either the export format or the output filename. The table below is from [](#frontmatter:exports).
+
+![](#table-frontmatter-exports)
+
+```{seealso} Exposing Exports as Downloads
+You can also include exported documents as downloads in your site, see [](./website-downloads.md).
+```

docs/frontmatter.md

@@ -80,10 +80,10 @@ The following table lists the available frontmatter fields, a brief description
   - a string (max 500 chars)
   - page & project
 * - `exports`
-  - an export object, see [](#exports)
+  - an export object, see [](./documents-exports.md)
   - page & project
 * - `downloads`
-  - a download object, see [](#downloads)
+  - a download object, see [](./website-downloads.md)
   - page & project
 * - `tags`
   - a list of strings
@@ -513,15 +513,12 @@ The date field is a string and should conform to a valid Javascript data format.
 
 Where the latter example in that list are valid [IETF timestamps](https://datatracker.ietf.org/doc/html/rfc2822#page-14)
 
-(exports)=
+(frontmatter:exports)=
 
 ## Exports
 
-You may define desired static exports in page or project frontmatter. In the export object, you may specify a filename, format, and/or template, as well as the article(s) you wish to include in your export. You may also provide any additional options required by your template in the export object. Formats currently supported by MyST include `pdf`, `tex`, `typst`, `docx`, `jats`, and `meca`. For examples of how to create exports, see [](./creating-pdf-documents.md). You can also explore the [MyST templating](myst:jtex) documentation for a deeper dive into defining templates.
-
-After defining `exports` in your frontmatter, you may build them with the `myst build` [CLI command](./quickstart-myst-documents.md).
-
-The following table shows the available properties for each export. You must define at least one of `format`, `output`, or `template` for MyST to be able to perform your output. You may also specify a string instead of a full export object; this string will be inferred to be either the export format or the output filename.
+Exports allow you to generate static versions of your MyST documents, often through intermediary build engines like Latex.
+For usage information, see [](./documents-exports.md).
 
 ```{list-table} Frontmatter export definitions
 :header-rows: 1
@@ -546,11 +543,34 @@ The following table shows the available properties for each export. You must def
   - a list of strings - path(s) to sub-articles for `jats` export
 ```
 
-(downloads)=
+(frontmatter:downloads)=
 
 ## Downloads
 
-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. In your frontmatter, a download may only specify one of `id`, `file`, or `url`. Descriptions of these fields and other available fields are in the table below.
+Downloads allow you to include downloadable files with a MyST website.
+They are specified in either:
+
+```{code-block} yaml
+:filename: myst.yml
+project:
+  downloads:
+    - file: ...
+    - id: ...
+```
+
+In **page frontmatter**:
+
+```{code-block} yaml
+:filename: page.md
+---
+downloads:
+  - file: ...
+  - id: ...
+---
+```
+
+See [](./website-downloads.md) information about how to use this feature.
+Below is a list of all possible downloads configuration.
 
 ```{list-table} Frontmatter download definitions
 :header-rows: 1
@@ -571,33 +591,6 @@ Downloads are downloadable files or useful links you want available on your MyST
   - 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.
 ```
 
-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:
-
-```yaml
-downloads:
-  file: index.md
-  title: Source File
-```
-
-The following example has several downloads: the source file, as above, an exported pdf, a remote file, and a link to another website:
-
-```yaml
-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
-```
-
 (licenses)=
 
 ## Licenses