diff --git a/.changeset/grumpy-cobras-thank.md b/.changeset/grumpy-cobras-thank.md deleted file mode 100644 index ff597adc40..0000000000 --- a/.changeset/grumpy-cobras-thank.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -"myst-cli": patch -"myst-common": patch -"myst-spec-ext": patch ---- - -Add support for notebook cell output scroll metadata diff --git a/.changeset/lucky-tools-behave.md b/.changeset/lucky-tools-behave.md deleted file mode 100644 index d1a7c8958a..0000000000 --- a/.changeset/lucky-tools-behave.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'myst-cli': patch ---- - -Fix static build inclusion of sitemap diff --git a/.changeset/red-yaks-rule.md b/.changeset/red-yaks-rule.md deleted file mode 100644 index 9544010dfc..0000000000 --- a/.changeset/red-yaks-rule.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'myst-cli': patch ---- - -Drop hide_authors handling in mystmd diff --git a/docs/abbreviations.yml b/docs/abbreviations.yml new file mode 100644 index 0000000000..714e674b18 --- /dev/null +++ b/docs/abbreviations.yml @@ -0,0 +1,40 @@ +version: 1 +project: + + abbreviations: + # Alphabetical order + AMS: American Mathematical Society + API: Application Programming Interface + AST: Abstract Syntax Tree + CLI: Command Line Interface + CRediT: Contributor Roles Taxonomy + CSS: Cascading Style Sheet + CSV: comma-separated values + DOI: Digital Object Identifier + ESM: ECMAScript Modules + GPU: Graphics Processing Unit + HTML: Hypertext Markup Language + ID: Identifier + ISNI: International Standard Name Identifier + JATS: Journal Article Tag Suite + JSON: JavaScript Object Notation + LTS: Long Term Support + MyST: Markedly Structured Text + NISO: National Information Standards Organization + OA: Open Access + PDF: Portable Document Format + PID: Persistent Identifier + POSIX: Portable Operating System Interface + REES: Reproducible Execution Environment Specification + ROR: Research Organization Registry + RRID: Research Resource Identifier + RST: reStructuredText + SPDX: Software Package Data Exchange + TLA: Three Letter Acronym + TOC: table of contents + TPU: Tensor Processing Unit + URL: Uniform Resource Locator + VoR: Version of Record + WASM: WebAssembly + YAML: Yet Another Markup Language + XML: Extensible Markup Language \ No newline at end of file diff --git a/docs/admonitions.md b/docs/admonitions.md index a355ef2bd8..5cdd4271bd 100644 --- a/docs/admonitions.md +++ b/docs/admonitions.md @@ -5,15 +5,9 @@ thumbnail: ./thumbnails/admonitions.png --- Callouts, or "admonitions", highlight a particular block of text that exists slightly apart from the narrative of your page, such as a note or a warning. -For example, try changing the following example of a `{tip}` admonition to a `{warning}`: -```{myst} -:::{tip} -Try changing `tip` to `warning`! -::: -``` -In MyST we call these kinds of directives {myst:directive}`admonitions `, however, they are almost always used through their _named_ directives, like {myst:directive}`note` or {myst:directive}`danger`. There are ten kinds[^docutils-admonitions] of admonitions available: +In MyST we call these kinds of directives {myst:directive}`admonitions `, however, they are almost always used through their _named_ directives, like {myst:directive}`note` or {myst:directive}`danger`. There are ten kinds[^docutils-admonitions] of admonitions available by default, and others may be introduced by [plugins](./plugins.md): ```{list-table} Named admonitions that can be used as directives :label: admonitions-list @@ -31,6 +25,14 @@ In MyST we call these kinds of directives {myst:directive}`admonitions ` or `[](doi:10.5281/zenodo.6476040)`,\ -which will insert the citation text in the correct format (e.g. adding an italic "_et al._", etc.). If the DOI is present on a citation from a BibTeX file in your project, that citation will be used. Otherwise, the citation data for these DOIs will be downloaded from `https://doi.org` once and cached to a local file in the `_build` directory. This cache may be cleared with `myst clean --cache`. +which will insert the citation text in the correct format (e.g. adding an italic "_et al._", etc.). +If the DOI is present on a citation from a BibTeX file in your project, that citation will be used. +Otherwise, the citation data for these DOIs will be downloaded from `https://doi.org` once and cached to a local file in the `_build` directory. +This cache may be cleared with `myst clean --cache`. -Providing your DOIs as full links has the advantage that on other rendering platforms (e.g. GitHub), your citation will still be shown as a link. If you have many citations, however, this will slow down the build process as the citation information is fetched dynamically. +Providing your DOIs as full links has the advantage that on other rendering platforms (e.g. GitHub), your citation will still be shown as a link. +If you have many citations, however, this will slow down the build process as the citation information is fetched dynamically. :::{note} Dealing with complex DOIs :class: dropdown @@ -52,19 +60,21 @@ site: ### Writing DOIs to BibTeX -If you encounter problems fetching DOIs from `https://doi.org`, for example the downloaded citation does not include all the data you expect or requests to `https://doi.org` are failing on an automated continuous integration platform, you may write your DOI citations to file using the MyST command +If you encounter problems fetching DOIs from `https://doi.org`, for example the downloaded citation does not include all the data you expect or requests to `https://doi.org` are failing on an automated continuous integration platform, you may write your DOI citations to file using the MyST command: ```bash myst build --doi-bib ``` -This will generate a BibTeX file `myst.doi.bib` which you may then rename, edit, and save to your project. On subsequent builds, the DOIs will be loaded from this file rather than fetched remotely. +This will generate a BibTeX file `myst.doi.bib` which you may then rename, edit, and save to your project. +On subsequent builds, the DOIs will be loaded from this file rather than fetched remotely. ## Including BibTeX A standard way of including references for $\LaTeX$ is using , you can include a `*.bib` file or files in the same directory as your content directory for the project. These will provide the reference keys for that project. -If you want to explicitly reference which BibTeX files to use, as well as what order to resolve them in, you can use the `bibliography` field in your frontmatter, which is a string array of local or remote files. This will load the files in order specified. +If you want to explicitly reference which BibTeX files to use, as well as what order to resolve them in, you can use the `bibliography` field in your frontmatter, which is a string array of local or remote files. +This will load the files in order specified. ```yaml bibliography: @@ -77,7 +87,11 @@ The remote BibTeX can be helpful for working with reference managers that suppor ## Markdown Citations You can add citations to any BibTeX entry using the citation key preceded by an `@`, for example, `@author2023`. -This syntax follows the [pandoc citation syntax](https://pandoc.org/MANUAL.html#citation-syntax). Multiple citations can be grouped together with square brackets, separated with semi-colons. It is also possible to add a prefix or suffix to parenthetical citations, for example, `[e.g. @author2023, chap. 3; @author1995]`. To add a suffix to a narrative citation, follow the citation with the suffix in square brackets, for example, `@author2023 [chap. 3]`. As with a link to a DOI, you can also use the DOI directly instead of the BibTeX key. +This syntax follows the [pandoc citation syntax](https://pandoc.org/MANUAL.html#citation-syntax). +Multiple citations can be grouped together with square brackets, separated with semi-colons. +It is also possible to add a prefix or suffix to parenthetical citations, for example, `[e.g. @author2023, chap. 3; @author1995]`. +To add a suffix to a narrative citation, follow the citation with the suffix in square brackets, for example, `@author2023 [chap. 3]`. +As with a link to a DOI, you can also use the DOI directly instead of the BibTeX key. ```{list-table} Examples of Markdown citations :header-rows: 1 @@ -110,7 +124,8 @@ This syntax follows the [pandoc citation syntax](https://pandoc.org/MANUAL.html# ## Citation Roles -MyST also provides a number of roles for compatibility with Sphinx and Jupyter Book V1. To create a citation role in Markdown, use either a parenthetical or textual citation: +MyST also provides a number of roles for compatibility with Sphinx and Jupyter Book V1. +To create a citation role in Markdown, use either a parenthetical or textual citation: ```md This is a parenthetical citation {cite:p}`cockett2015`. diff --git a/docs/creating-pdf-documents.md b/docs/creating-pdf-documents.md index fa50165d29..f63afb2a44 100644 --- a/docs/creating-pdf-documents.md +++ b/docs/creating-pdf-documents.md @@ -178,6 +178,7 @@ myst templates list arxiv_two_column --tex There are two ways to provide information to a template, through `parts` and `options`. + ## Template `parts` 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. @@ -215,6 +216,47 @@ exports: Any unrecognized, or malformed entries will be logged as errors as well as required options that are not provided. + +### Setting options using extends +Using [extends](#composing-myst-yml) you can create an `export.yml` file which is referred to in the `myst.yml` file: + +```{code-block} yaml +:filename: myst.yml +--- +extends: + - export.yml +--- +``` + +in which you set these parts and options: + +```{code-block} yaml +:filename: export.yml +--- +version: 1 +project: + + downloads: + - id: output-pdf1 + + exports: + - id: output-pdf1 + format: typst + template: https://github.com/myst-templates/plain_typst_book + output: book.pdf + # additional options + + #### Cover picture + cover: Cover.PNG + #Coverposition: + # coverwidth: + + #### Logo at top of position + logo: logo.svg + logo_width: 10 +--- +``` + ## Creating a Template The export list can also point to local templates, for $\LaTeX$ these are built using [`jtex`](/jtex), and you can learn more about how to create a template for: [any $\LaTeX$ document](/jtex/create-a-latex-template) and [Beamer presentations](/jtex/create-a-beamer-template). @@ -239,7 +281,13 @@ Please consider [contributing your template](/jtex/contribute-a-template) to the ## Excluding Content from Specific Exports -If you have a block or notebook cell that you do not want to render to your $\LaTeX$ output, add the `no-tex` tag to the cell. Similarly, to exclude a cell from Typst, use `no-typst`. To exclude a cell from both formats, use `no-pdf`. +If you have a [block](./blocks.md) or notebook cell that you do not want to render to your $\LaTeX$ output, add the `no-tex` tag to the cell. Similarly, to exclude a cell from Typst, use `no-typst`. To exclude a cell from both formats, use `no-pdf`. + +````markdown ++++{"no-pdf": true} +This will not be in the pdf ++++ +```` ## Including Content with Specific Exports @@ -331,3 +379,4 @@ exports: title: Summary of this Thesis --- ``` + diff --git a/docs/exercises.md b/docs/exercises.md index 4a5b85cb34..f96e9b42e5 100644 --- a/docs/exercises.md +++ b/docs/exercises.md @@ -5,7 +5,8 @@ description: MyST supports adding exercises and solutions which can cross-refere thumbnail: ./thumbnails/exercise.png --- -There are two directives available to add exercises and solutions to your documents: (1) an `exercise` directive; and (2) a `solution` directive. The exercises are enumerated by default and can take in an optional title argument as well as be "gated" around Jupyter Notebook cells. +There are two directives available to add exercises and solutions to your documents: (1) an `exercise` directive; and (2) a `solution` directive. +The exercises are enumerated by default and can take in an optional title argument as well as be "gated" around Jupyter Notebook cells. ## Exercise Directive @@ -55,7 +56,10 @@ The following options for exercise directives are supported: ## Solution Directive -A solution directive can be included using the `solution` pattern. It takes in the label of the directive it wants to link to as a required argument. Unlike the `exercise` directive, the solution directive is not enumerable as it inherits numbering directly from the linked exercise. The argument for a solution is the label of the linked exercise, which is required. +A solution directive can be included using the `solution` pattern. +It takes in the label of the directive it wants to link to as a required argument. +Unlike the `exercise` directive, the solution directive is not enumerable as it inherits numbering directly from the linked exercise. +The argument for a solution is the label of the linked exercise, which is required. ::::{tab-set} :::{tab-item} Example @@ -138,7 +142,8 @@ For example,\ ### Referencing Solutions -You can refer to a solution directly as well using a Markdown link or using the {myst:role}`ref` role like: `` {ref}`my-solution` `` the output of which depends on the attributes of the linked directive. If the linked directive is enumerable, the role will replace the solution reference with the linked directive type and its appropriate number like so: {ref}`my-solution`. +You can refer to a solution directly as well using a Markdown link or using the {myst:role}`ref` role like: `` {ref}`my-solution` `` the output of which depends on the attributes of the linked directive. +If the linked directive is enumerable, the role will replace the solution reference with the linked directive type and its appropriate number like so: {ref}`my-solution`. In the event that the directive being referenced is unenumerable, the reference will display its title: {ref}`nfactorial-solution`. @@ -204,7 +209,8 @@ static int factorial(int n){ ## Alternative Gated Syntax -To be able to be viewed as Jupyter Notebooks (e.g. in [JupyterLab MyST](./quickstart-jupyter-lab-myst.md)) `code-cell` directives must be at the root level of the document for them to be executed. This maintains direct compatibility with the `jupyter notebook` and enables tools like `jupytext` to convert between `myst` and `ipynb` files. +To be able to be viewed as Jupyter Notebooks (e.g. in [JupyterLab MyST](./quickstart-jupyter-lab-myst.md)) `code-cell` directives must be at the root level of the document for them to be executed. +This maintains direct compatibility with the `jupyter notebook` and enables tools like `jupytext` to convert between `myst` and `ipynb` files. As a result **executable** `code-cell` directives cannot be nested inside of exercises or solution directives. @@ -264,7 +270,8 @@ and maybe you wish to add a figure ::: :::: -This can also be completed for solutions with `solution-start` and `solution-end` directives. The `solution-start` and `exercise-start` directives have the same options as original directive. +This can also be completed for solutions with `solution-start` and `solution-end` directives. +The `solution-start` and `exercise-start` directives have the same options as original directive. ```{warning} Mismatched Start & End :class: dropdown @@ -326,5 +333,11 @@ This is a hidden exercise directive. ``` ```` +## Exporting exercises and solutions + +When exporting content which include exercises and solutions to pdf using either LaTeX or Typst, warning errors are raised since these directives are not natively supported in these formats. +A plugin is [available](https://github.com/jupyter-book/myst-plugins/tree/main/plugins/exercise-admonition-pdf) to enable exporting these directives to pdf formats - including numeration. + + % TODO: Remove All Solutions % TODO: Custom CSS diff --git a/docs/figures.md b/docs/figures.md index e0c4b11084..11f393cbea 100644 --- a/docs/figures.md +++ b/docs/figures.md @@ -9,7 +9,7 @@ MyST Markdown can be used to include images and figures in your documents as wel ## Simple images -The simplest way to create an image is to use the standard Markdown syntax: +The simplest way to include an image is to use the standard Markdown syntax: ```md ![alt](link 'title') @@ -17,12 +17,14 @@ The simplest way to create an image is to use the standard Markdown syntax: You can explore a [demo of images](#md:image) in the discussion of [](./commonmark.md) features of MyST. -Using standard markdown to create an image will render across all output formats (HTML, TeX, Word, PDF, etc). However, this markdown syntax is limited in the configuration that can be applied beyond `alt` text and an optional `title`. +Using standard markdown to create an image will render across all output formats (HTML, TeX, Word, PDF, etc). +However, this markdown syntax is limited in the configuration that can be applied beyond `alt` text and an optional `title`. -There are two directives that can be used to add additional information about the layout and metadata associated with an image. For example, {myst:directive}`image.width`, {myst:directive}`alignment ` or a {myst:directive}`figure caption `. +There are two directives that can be used to add additional information about the layout and metadata associated with an image. +For example, {myst:directive}`image.width`, {myst:directive}`alignment ` or a {myst:directive}`figure caption `. **image** -: The {myst:directive}`image` directive allows you to customize {myst:directive}`image.width`, {myst:directive}`alignment `, and other {myst:directive}`classes ` to add to the image +: The {myst:directive}`image` directive allows you to customize {myst:directive}`image.width`, {myst:directive}`alignment `, and other {myst:directive}`classes ` to add to the image. **figure** : The {myst:directive}`figure` directive can contain a {myst:directive}`figure caption ` and allows you to cross-reference this in other parts of your document. @@ -72,7 +74,9 @@ These will be numbered as `Figure 1a` and `Figure 1b`, etc. For example: We saw some great things on our trips this year to Banff, Canada 🇨🇦 and San Francisco, USA 🌉. ::: -You can also cross-reference either the whole figure [@subFigure], or an individual subfigure [@subFigure-a] or [@subFigure-b]. Each subfigure is given an implicit reference that matches the figure label with a suffix of their letter, for example, a figure with label `my-figure` the two subfigures can be referred to as `my-figure-a` and `my-figure-b`, respectively. If you provide a [specific label for a subfigure](#label-anything), that label will be used instead of the implicit label. +You can also cross-reference either the whole figure [@subFigure], or an individual subfigure [@subFigure-a] or [@subFigure-b]. +Each subfigure is given an implicit reference that matches the figure label with a suffix of their letter, for example, a figure with label `my-figure` the two subfigures can be referred to as `my-figure-a` and `my-figure-b`, respectively. +If you provide a [specific label for a subfigure](#label-anything), that label will be used instead of the implicit label. ```{myst} :::{figure} @@ -90,12 +94,32 @@ Some pictures of fruit and the ocean! See [](#my-figure-fruit) for the fruit, and [](#my-figure) to reference both subfigures. ``` -By default, when referring to subfigures, the `{number}` that is used includes the parent enumerator (that is: `1a` rather than just `a`). To specifically use the sub-enumerator only, you can use the syntax `{subEnumerator}` in your text link which will be replaced with the sub-enumerator (that is: `a` rather than `1a`). +When referring to subfigures, the `{number}` that is used includes the parent enumerator by default (that is: `1a` rather than just `a`). +To specifically use the sub-enumerator only, you can use the syntax `{subEnumerator}` in your text link which will be replaced with the sub-enumerator (that is: `a` rather than `1a`). + +CSS classes can be applied to make subfigures appear side-by-side or in a grid layout. +`:class: grid grid-cols-2 items-end gap-4` +can be used to create a two-column grid of images with aligned bottoms and a gap between them. + +::::{figure} +:class: grid grid-cols-2 items-end gap-4 +:label: fig_combined2 +:width: 100% + +![Banff, Canada](https://github.com/rowanc1/pics/blob/main/banff-wide.png) +![Golden Gate Bridge, San Francisco](https://github.com/rowanc1/pics/blob/main/sfo-wide.png) + +Some lovely pictures +:::: + + ## Supported Image Formats MyST supports many images formats including `.png`, `.jpg`, `.gif`, `.tiff`, `.svg`, `.pdf`, and `.eps`. -Many of these image formats are easily supported for HTML themes including `.png`, `.jpg` and `.gif`. However, the raster image formats can be further optimized to [improve site performance](./accessibility-and-performance.md), MyST translates these to the modern `.webp` format while the site is building. The original file-format is also included your site, with a `srcset` and fallback for older web-browsers. +Many of these image formats are easily supported for HTML themes including `.png`, `.jpg` and `.gif`. +However, the raster image formats can be further optimized to [improve site performance](./accessibility-and-performance.md), MyST translates these to the modern `.webp` format while the site is building. +The original file-format is also included your site, with a `srcset` and fallback for older web-browsers. `````{tab-set} ````{tab-item} PNG @@ -150,7 +174,10 @@ An `.eps` image is not supported by web-browsers or Microsoft Word. The images a ### Image Transformers -There are formats that are not supported by web-browsers but are common in scientific writing like `.tiff`, `.pdf` and `.eps` for site builds, these are converted to `.svg` or `.png` as appropriate and available. For export to $\LaTeX$, PDF or Microsoft Word, the files are converted to an appropriate format that the export can handle (e.g. $\LaTeX$ can work directly with `.pdf` images). For animated images, `.gif`, the first frame is extracted for static exports. +There are formats that are not supported by web-browsers but are common in scientific writing like `.tiff`, `.pdf` and `.eps`. +For site builds, these are converted to `.svg` or `.png` as appropriate and available. +For export to $\LaTeX$, PDF or Microsoft Word, the files are converted to an appropriate format that the export can handle (e.g. $\LaTeX$ can work directly with `.pdf` images). +For animated images, `.gif`, the first frame is extracted for static exports. :::{tip} Installing Image Converters :class: dropdown @@ -166,13 +193,15 @@ The image transforms and optimizations requires you to have the following packag ### Multiple Images -If you have manually converted your images or have different images for different formats, use an asterisk (`*`) as the extension. All images matching the provided pattern will be found and the best image out of the available candidates will be used for the export: +If you have manually converted your images or have different images for different formats, use an asterisk (`*`) as the extension. +All images matching the provided pattern will be found and the best image available will be used for the export: ```text ![](./images/myst-image.*) ``` -For example, when exporting to $\LaTeX$ the best format is a `.pdf` if it is available; in a web export, a `.webp` or `.svg` will be chosen before a `.png`. In all cases, if an appropriate format is not available the image will be translated. +For example, when exporting to $\LaTeX$ the best format is a `.pdf` (if available); in a web export, a `.webp` or `.svg` will be chosen before a `.png`. +In all cases, if an appropriate format is not available the image will be converted. ## Videos @@ -182,9 +211,9 @@ To embed a video you can either use a video platforms embed script or directly e :::{figure} ./videos/links.mp4 An embedded video with a caption! ::: - +``` or - +```markdown ![](./videos/links.mp4) ``` @@ -194,7 +223,8 @@ will copy the video to your static files and embed a video in your HTML output. An embedded video with a caption! ::: -If you have [ffmpeg](https://www.ffmpeg.org/) installed, you may also include `.mov` and `.avi` video files, and MyST will convert them to `.mp4` and include them. Videos can also be used in the [image](#image-directive) or even in simple [Markdown image](#md:image). +If you have [ffmpeg](https://www.ffmpeg.org/) installed, you may also include `.mov` and `.avi` video files, and MyST will convert them to `.mp4` and include them. +Videos can also be used in the [image](#image-directive) or even in simple [Markdown image](#md:image). ### Use an image in place of a video for static exports diff --git a/docs/myst.yml b/docs/myst.yml index a5f8195a38..3b0788dfa1 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -16,43 +16,7 @@ project: jtex: https://mystmd.org/jtex/ spec: https://mystmd.org/spec/ biapol: https://biapol.github.io/blog/ - abbreviations: - # Alphabetical order - AMS: American Mathematical Society - API: Application Programming Interface - AST: Abstract Syntax Tree - CLI: Command Line Interface - CRediT: Contributor Roles Taxonomy - CSS: Cascading Style Sheet - CSV: comma-separated values - DOI: Digital Object Identifier - ESM: ECMAScript Modules - GPU: Graphics Processing Unit - HTML: Hypertext Markup Language - ID: Identifier - ISNI: International Standard Name Identifier - JATS: Journal Article Tag Suite - JSON: JavaScript Object Notation - LTS: Long Term Support - MyST: Markedly Structured Text - NISO: National Information Standards Organization - OA: Open Access - PDF: Portable Document Format - PID: Persistent Identifier - POSIX: Portable Operating System Interface - REES: Reproducible Execution Environment Specification - ROR: Research Organization Registry - RRID: Research Resource Identifier - RST: reStructuredText - SPDX: Software Package Data Exchange - TLA: Three Letter Acronym - TOC: table of contents - TPU: Tensor Processing Unit - URL: Uniform Resource Locator - VoR: Version of Record - WASM: WebAssembly - YAML: Yet Another Markup Language - XML: Extensible Markup Language + plugins: - directives.mjs - picsum.mjs @@ -66,6 +30,7 @@ project: path: markup.py - type: javascript path: markup.mjs + error_rules: - rule: link-resolves severity: ignore @@ -77,6 +42,7 @@ project: - /jtex/create-a-latex-template - /jtex/create-a-beamer-template - /jtex/contribute-a-template + toc: - file: index.md - file: installing.md @@ -186,6 +152,9 @@ project: - file: contribute-add-feature.md - file: cite.md +extends: + - abbreviations.yml + site: title: MyST Markdown Guide #template: ../../myst-theme/.deploy/book/template.yml diff --git a/docs/table-of-contents.md b/docs/table-of-contents.md index 5560fc8b45..10a7255470 100644 --- a/docs/table-of-contents.md +++ b/docs/table-of-contents.md @@ -270,3 +270,36 @@ New users should use `myst.yml` instead. Jupyter Book v2 uses the MyST engine, but Jupyter Book v1 uses a different configuration structure that is designed for Sphinx. However, you can currently use a Jupyter Book v1 Table of Contents file (`_toc.yml`) with MyST.The documentation for this format is fully described in [Jupyter Book](https://jupyterbook.org/en/stable/structure/toc.html). :::: + +## Configure your Table of Contents in a separate file using `extend:` +If your Table of Contents is very long, it can make your `myst.yml` difficult to read and maintain. You can use [`extends:` functionality](#composing-myst-yml) to store the ToC structure in a separate file, allowing you to re-use it in a modular way. + +```{code-block} yaml +:filename: myst.yml +--- +version: 1 +project: + [..] + +extends: + - toc.yml + +site: + [..] +--- +``` + +```{code-block} yaml +:filename: toc.yml +--- +version: 1 +project: + toc: + - file: index.md + - title: Some title + children: + - file: introduction/about.md + - file: introduction/credits.md +--- +``` + diff --git a/package-lock.json b/package-lock.json index a15fc2468e..5b186e2891 100644 --- a/package-lock.json +++ b/package-lock.json @@ -15316,7 +15316,7 @@ } }, "packages/myst-cli": { - "version": "1.6.6", + "version": "1.6.7", "license": "MIT", "dependencies": { "@jupyterlab/services": "^7.3.0", @@ -15346,8 +15346,8 @@ "meca": "^1.0.8", "mime-types": "^2.1.35", "myst-cli-utils": "^2.0.12", - "myst-common": "^1.9.0", - "myst-config": "^1.9.0", + "myst-common": "^1.9.1", + "myst-config": "^1.9.1", "myst-execute": "^0.3.0", "myst-ext-button": "^0.0.1", "myst-ext-card": "^1.0.9", @@ -15357,10 +15357,10 @@ "myst-ext-proof": "^1.0.12", "myst-ext-reactive": "^1.0.9", "myst-ext-tabs": "^1.0.9", - "myst-frontmatter": "^1.9.0", + "myst-frontmatter": "^1.9.1", "myst-parser": "^1.6.1", "myst-spec": "^0.0.5", - "myst-spec-ext": "^1.9.0", + "myst-spec-ext": "^1.9.1", "myst-templates": "^1.0.26", "myst-to-docx": "^1.0.15", "myst-to-jats": "^1.0.34", @@ -15537,11 +15537,11 @@ } }, "packages/myst-common": { - "version": "1.9.0", + "version": "1.9.1", "license": "MIT", "dependencies": { "mdast": "^3.0.0", - "myst-frontmatter": "^1.9.0", + "myst-frontmatter": "^1.9.1", "myst-spec": "^0.0.5", "nanoid": "^5.1.6", "unified": "^10.1.2", @@ -15554,7 +15554,7 @@ "devDependencies": { "@jupyterlab/nbformat": "^3.5.2", "@lumino/coreutils": "^2.0.0", - "myst-spec-ext": "^1.9.0", + "myst-spec-ext": "^1.9.1", "unist-builder": "3.0.0" } }, @@ -15565,11 +15565,11 @@ "dev": true }, "packages/myst-config": { - "version": "1.9.0", + "version": "1.9.1", "license": "MIT", "dependencies": { - "myst-common": "^1.9.0", - "myst-frontmatter": "^1.9.0", + "myst-common": "^1.9.1", + "myst-frontmatter": "^1.9.1", "simple-validators": "^1.1.1" }, "devDependencies": { @@ -15729,7 +15729,7 @@ } }, "packages/myst-frontmatter": { - "version": "1.9.0", + "version": "1.9.1", "license": "MIT", "dependencies": { "credit-roles": "^2.1.0", @@ -15748,7 +15748,7 @@ } }, "packages/myst-migrate": { - "version": "1.6.6", + "version": "1.6.7", "license": "MIT", "dependencies": { "unist-util-select": "^4.0.3", @@ -15807,7 +15807,7 @@ } }, "packages/myst-spec-ext": { - "version": "1.9.0", + "version": "1.9.1", "license": "MIT", "dependencies": { "myst-spec": "^0.0.5" @@ -16096,7 +16096,7 @@ } }, "packages/mystmd": { - "version": "1.6.6", + "version": "1.6.7", "license": "MIT", "bin": { "myst": "dist/myst.cjs" @@ -16106,7 +16106,7 @@ "commander": "^10.0.1", "core-js": "^3.31.1", "js-yaml": "^4.1.0", - "myst-cli": "^1.6.6" + "myst-cli": "^1.6.7" } }, "packages/mystmd-ext-icon": { diff --git a/packages/myst-cli/CHANGELOG.md b/packages/myst-cli/CHANGELOG.md index 5ba8c82841..22339f6b5b 100644 --- a/packages/myst-cli/CHANGELOG.md +++ b/packages/myst-cli/CHANGELOG.md @@ -1,5 +1,18 @@ # myst-cli +## 1.6.7 + +### Patch Changes + +- a742dda: Add support for notebook cell output scroll metadata +- 39570e5: Fix static build inclusion of sitemap +- ae32040: Drop hide_authors handling in mystmd +- Updated dependencies [a742dda] + - myst-common@1.9.1 + - myst-spec-ext@1.9.1 + - myst-config@1.9.1 + - myst-frontmatter@1.9.1 + ## 1.6.6 ## 1.6.5 diff --git a/packages/myst-cli/package.json b/packages/myst-cli/package.json index 1deccc3c5d..3bf985d49d 100644 --- a/packages/myst-cli/package.json +++ b/packages/myst-cli/package.json @@ -1,6 +1,6 @@ { "name": "myst-cli", - "version": "1.6.6", + "version": "1.6.7", "description": "Command line tools for MyST", "author": "Franklin Koch ", "license": "MIT", @@ -69,8 +69,8 @@ "meca": "^1.0.8", "mime-types": "^2.1.35", "myst-cli-utils": "^2.0.12", - "myst-common": "^1.9.0", - "myst-config": "^1.9.0", + "myst-common": "^1.9.1", + "myst-config": "^1.9.1", "myst-execute": "^0.3.0", "myst-ext-button": "^0.0.1", "myst-ext-card": "^1.0.9", @@ -80,10 +80,10 @@ "myst-ext-proof": "^1.0.12", "myst-ext-reactive": "^1.0.9", "myst-ext-tabs": "^1.0.9", - "myst-frontmatter": "^1.9.0", + "myst-frontmatter": "^1.9.1", "myst-parser": "^1.6.1", "myst-spec": "^0.0.5", - "myst-spec-ext": "^1.9.0", + "myst-spec-ext": "^1.9.1", "myst-templates": "^1.0.26", "myst-to-docx": "^1.0.15", "myst-to-jats": "^1.0.34", diff --git a/packages/myst-common/CHANGELOG.md b/packages/myst-common/CHANGELOG.md index 677b7b2f0b..60ff55f898 100644 --- a/packages/myst-common/CHANGELOG.md +++ b/packages/myst-common/CHANGELOG.md @@ -1,5 +1,12 @@ # myst-common +## 1.9.1 + +### Patch Changes + +- a742dda: Add support for notebook cell output scroll metadata + - myst-frontmatter@1.9.1 + ## 1.9.0 ### Patch Changes diff --git a/packages/myst-common/package.json b/packages/myst-common/package.json index 2a5c60c0eb..5c15fe55f4 100644 --- a/packages/myst-common/package.json +++ b/packages/myst-common/package.json @@ -1,7 +1,7 @@ { "name": "myst-common", "sideEffects": false, - "version": "1.9.0", + "version": "1.9.1", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -21,7 +21,7 @@ }, "dependencies": { "mdast": "^3.0.0", - "myst-frontmatter": "^1.9.0", + "myst-frontmatter": "^1.9.1", "myst-spec": "^0.0.5", "nanoid": "^5.1.6", "unified": "^10.1.2", @@ -32,7 +32,7 @@ "vfile-message": "^3.0.0" }, "devDependencies": { - "myst-spec-ext": "^1.9.0", + "myst-spec-ext": "^1.9.1", "unist-builder": "3.0.0", "@jupyterlab/nbformat": "^3.5.2", "@lumino/coreutils": "^2.0.0" diff --git a/packages/myst-config/CHANGELOG.md b/packages/myst-config/CHANGELOG.md index a9ff7c3ed9..ddc29ed6ac 100644 --- a/packages/myst-config/CHANGELOG.md +++ b/packages/myst-config/CHANGELOG.md @@ -1,5 +1,13 @@ # myst-config +## 1.9.1 + +### Patch Changes + +- Updated dependencies [a742dda] + - myst-common@1.9.1 + - myst-frontmatter@1.9.1 + ## 1.9.0 ### Patch Changes diff --git a/packages/myst-config/package.json b/packages/myst-config/package.json index ea65f72c05..f4ce9b175f 100644 --- a/packages/myst-config/package.json +++ b/packages/myst-config/package.json @@ -1,6 +1,6 @@ { "name": "myst-config", - "version": "1.9.0", + "version": "1.9.1", "license": "MIT", "description": "Project and site config types and validation for the mystmd ecosystem", "author": "Franklin Koch ", @@ -31,8 +31,8 @@ "url": "https://github.com/jupyter-book/mystmd/issues" }, "dependencies": { - "myst-common": "^1.9.0", - "myst-frontmatter": "^1.9.0", + "myst-common": "^1.9.1", + "myst-frontmatter": "^1.9.1", "simple-validators": "^1.1.1" }, "devDependencies": { diff --git a/packages/myst-frontmatter/CHANGELOG.md b/packages/myst-frontmatter/CHANGELOG.md index c943fd617f..fa962f8b91 100644 --- a/packages/myst-frontmatter/CHANGELOG.md +++ b/packages/myst-frontmatter/CHANGELOG.md @@ -1,5 +1,7 @@ # myst-frontmatter +## 1.9.1 + ## 1.9.0 ### Minor Changes diff --git a/packages/myst-frontmatter/package.json b/packages/myst-frontmatter/package.json index 060dbd1118..f28188c1d6 100644 --- a/packages/myst-frontmatter/package.json +++ b/packages/myst-frontmatter/package.json @@ -1,6 +1,6 @@ { "name": "myst-frontmatter", - "version": "1.9.0", + "version": "1.9.1", "sideEffects": false, "license": "MIT", "description": "Frontmatter types and validation for the mystmd ecosystem", diff --git a/packages/myst-migrate/CHANGELOG.md b/packages/myst-migrate/CHANGELOG.md index d600ef6e61..05a67ce469 100644 --- a/packages/myst-migrate/CHANGELOG.md +++ b/packages/myst-migrate/CHANGELOG.md @@ -1,5 +1,7 @@ # myst-migrate +## 1.6.7 + ## 1.6.6 ## 1.6.5 diff --git a/packages/myst-migrate/package.json b/packages/myst-migrate/package.json index 70a73a3c3e..bca3213dd7 100644 --- a/packages/myst-migrate/package.json +++ b/packages/myst-migrate/package.json @@ -1,7 +1,7 @@ { "name": "myst-migrate", "sideEffects": false, - "version": "1.6.6", + "version": "1.6.7", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", diff --git a/packages/myst-spec-ext/CHANGELOG.md b/packages/myst-spec-ext/CHANGELOG.md index e7a4e2e34b..09a86c4e19 100644 --- a/packages/myst-spec-ext/CHANGELOG.md +++ b/packages/myst-spec-ext/CHANGELOG.md @@ -1,5 +1,11 @@ # myst-spec-ext +## 1.9.1 + +### Patch Changes + +- a742dda: Add support for notebook cell output scroll metadata + ## 1.9.0 ### Patch Changes diff --git a/packages/myst-spec-ext/package.json b/packages/myst-spec-ext/package.json index 62e69a22e8..bc85690a7b 100644 --- a/packages/myst-spec-ext/package.json +++ b/packages/myst-spec-ext/package.json @@ -1,6 +1,6 @@ { "name": "myst-spec-ext", - "version": "1.9.0", + "version": "1.9.1", "description": "Extensions for myst-spec that are used in mystmd", "author": "Rowan Cockett ", "homepage": "https://github.com/jupyter-book/mystmd/tree/main/packages/myst-spec-ext", diff --git a/packages/mystmd/CHANGELOG.md b/packages/mystmd/CHANGELOG.md index 13141e4f21..1f82254fff 100644 --- a/packages/mystmd/CHANGELOG.md +++ b/packages/mystmd/CHANGELOG.md @@ -1,5 +1,7 @@ # mystmd +## 1.6.7 + ## 1.6.6 ### Patch Changes diff --git a/packages/mystmd/package.json b/packages/mystmd/package.json index 6a2580286d..92e413ef34 100644 --- a/packages/mystmd/package.json +++ b/packages/mystmd/package.json @@ -1,6 +1,6 @@ { "name": "mystmd", - "version": "1.6.6", + "version": "1.6.7", "description": "Command line tools for MyST Markdown", "author": "Rowan Cockett ", "license": "MIT", @@ -45,6 +45,6 @@ "commander": "^10.0.1", "core-js": "^3.31.1", "js-yaml": "^4.1.0", - "myst-cli": "^1.6.6" + "myst-cli": "^1.6.7" } }