From 10813e822af2f06bc4dc4c0781e3db6d7c3e4f14 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Fri, 5 Apr 2024 15:37:03 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20Add=20dedicated=20exports=20and?= =?UTF-8?q?=20downloads=20pages=20(#1064)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Rowan Cockett --- docs/_toc.yml | 2 + docs/creating-pdf-documents.md | 46 +++++++++-------- docs/document-parts.md | 6 +++ docs/documents-exports.md | 58 ++++++++++++++++++++++ docs/frontmatter.md | 67 ++++++++++++------------- docs/website-downloads.md | 90 ++++++++++++++++++++++++++++++++++ 6 files changed, 212 insertions(+), 57 deletions(-) create mode 100644 docs/documents-exports.md create mode 100644 docs/website-downloads.md diff --git a/docs/_toc.yml b/docs/_toc.yml index e335296ba..828430413 100644 --- a/docs/_toc.yml +++ b/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 diff --git a/docs/creating-pdf-documents.md b/docs/creating-pdf-documents.md index 16ac076c6..a9b07cb46 100644 --- a/docs/creating-pdf-documents.md +++ b/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: diff --git a/docs/document-parts.md b/docs/document-parts.md index 1bb064e53..647b07929 100644 --- a/docs/document-parts.md +++ b/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): diff --git a/docs/documents-exports.md b/docs/documents-exports.md new file mode 100644 index 000000000..bcb95d8e2 --- /dev/null +++ b/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). +``` diff --git a/docs/frontmatter.md b/docs/frontmatter.md index d154e1360..9ebec9c4a 100644 --- a/docs/frontmatter.md +++ b/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 diff --git a/docs/website-downloads.md b/docs/website-downloads.md new file mode 100644 index 000000000..f09803020 --- /dev/null +++ b/docs/website-downloads.md @@ -0,0 +1,90 @@ +--- +title: Downloads, Links and Static Files +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. + +- 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. + +## Download links configuration + +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](#frontmatter:downloads). + +![](#table-frontmatter-downloads) + +## Include a built PDF + +If you want to include a PDF of your document with the downloads, take these steps: + +1. **Build the PDF**. For examples of how to build PDFs, see [](creating-pdf-documents.md). Let's say the PDF was output to `./mydoc.pdf`. +2. **Specify the file path in your page's metadata**. The filepath should point to the location of the built PDF relative to the page. + +```{code-block} yaml +:filename: article.md +--- +downloads: + - file: ./mydoc.pdf + title: A PDF of this document +--- +``` + +An entry for this PDF will now show up in your page's downloads dropdown. +If you do not specify the output location of your export we recommend that you refer to it by an ID, +rather than linking to the `./_build/exports` folder, as these may change depending on your exports list. See [below](#multiple-downloads) for an example. + +## Specify a download for all pages of a MyST site + +If you'd like a download link to show up for all pages of a MyST site, use configuration at the `myst.yml` level. +For example, let's say you used `typst` to generate a PDF of _all documents in your MyST site_, called `mybook.pdf`. + +```{code-block} yaml +:filename: myst.yml +project: + downloads: + - file: mybook.pdf + title: A PDF of this book +``` + +## Include the 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: + +```yaml +downloads: + - file: index.md + title: Source File +``` + +(multiple-downloads)= + +## 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. + +```{code-block} yaml +:filename: 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 +--- +```