diff --git a/.changeset/config.json b/.changeset/config.json index dd2c20f42..79e3a6265 100644 --- a/.changeset/config.json +++ b/.changeset/config.json @@ -5,7 +5,8 @@ "fixed": [ ["myst-to-jats", "jats-to-myst"], ["myst-to-tex", "tex-to-myst"], - ["myst-parser", "myst-roles", "myst-directives", "myst-to-html"] + ["myst-parser", "myst-roles", "myst-directives", "myst-to-html"], + ["mystmd", "myst-cli"] ], "linked": [], "access": "public", diff --git a/.changeset/little-pans-brake.md b/.changeset/little-pans-brake.md new file mode 100644 index 000000000..558a1cb6e --- /dev/null +++ b/.changeset/little-pans-brake.md @@ -0,0 +1,33 @@ +--- +'citation-js-utils': patch +'myst-ext-exercise': patch +'myst-ext-reactive': patch +'simple-validators': patch +'markdown-it-myst': patch +'myst-frontmatter': patch +'myst-directives': patch +'myst-transforms': patch +'myst-cli-utils': patch +'myst-ext-proof': patch +'myst-templates': patch +'myst-ext-card': patch +'myst-ext-grid': patch +'myst-ext-tabs': patch +'myst-spec-ext': patch +'jats-to-myst': patch +'myst-to-docx': patch +'myst-to-html': patch +'myst-to-jats': patch +'myst-common': patch +'myst-config': patch +'myst-parser': patch +'myst-to-tex': patch +'tex-to-myst': patch +'myst-roles': patch +'myst-to-md': patch +'myst-cli': patch +'mystmd': patch +'jtex': patch +--- + +Move repositories from mystjs --> mystmd diff --git a/.github/ISSUE_TEMPLATE/0-bug-report.yml b/.github/ISSUE_TEMPLATE/0-bug-report.yml index aeb1bc792..babbc69e3 100644 --- a/.github/ISSUE_TEMPLATE/0-bug-report.yml +++ b/.github/ISSUE_TEMPLATE/0-bug-report.yml @@ -7,7 +7,7 @@ body: value: Thank you for taking the time to file a bug report! Please fill out this form as completely as possible. - type: input attributes: - label: What version of `mystjs` are you using? + label: What version of `mystmd` are you using? description: 'For example: 1.0.0, use `myst -v`' validations: required: true diff --git a/.gitignore b/.gitignore index 15dc89013..7f9ce3cd3 100644 --- a/.gitignore +++ b/.gitignore @@ -38,3 +38,6 @@ _build # yalc .yalc yalc.lock + + +packages/mystmd/**.cjs diff --git a/README.md b/README.md index dfb6a58b9..a20ff6677 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,53 @@ -# MyST Markdown Tools +# MyST Markdown Command Line Interface, `mystmd` -[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/executablebooks/mystjs/blob/main/LICENSE) -![CI](https://github.com/executablebooks/mystjs/workflows/CI/badge.svg) +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/executablebooks/mystmd/blob/main/LICENSE) +![CI](https://github.com/executablebooks/mystmd/workflows/CI/badge.svg) -`mystjs` is a set of open-source, community-driven tools designed for scientific communication, including a powerful authoring framework that supports blogs, online books, scientific papers, reports and journals articles. +`mystmd` is a set of open-source, community-driven tools designed for scientific communication, including a powerful authoring framework that supports blogs, online books, scientific papers, reports and journals articles. > **Note** -> The `mystjs` project is in **beta**. It is being used to explore a full MyST implementation in JavaScript and will change significantly and rapidly. +> The `mystmd` project is in **beta**. It is being used to explore a full MyST implementation and will change significantly and rapidly. > The project is being developed by a small team of people on the Executable Books Project, and may make rapid decisions without fully public/inclusive discussion. > We will continue to update this documentation as the project stabilizes. ## Overview -The `mystjs` project provides a parser in Javascript (`mystjs`) and command line tool (`myst-cli`) for working with MyST Markdown projects. +The `mystmd` project provides a command line tool (`mystmd`) for working with MyST Markdown projects. -- Parse MyST into a standardized AST, that follows the MyST Spec - Provides functionality for cross-referencing, external structured links, and scientific citations -- Translate and render MyST into: +- Translate and render MyST Markdown into: - HTML for static websites, and modern React for interactive websites (like this website!) - PDFs and LaTeX documents, with specific templates for over 400 journals - Microsoft Word export +- Parse MyST into a standardized AST, that follows the MyST Markdown Spec See the [documentation](https://mystmd.org/guide). ## Get Started -The MyST CLI is available through Node and NPM: +The MyST Markdown CLI is available through Node and NPM: ```bash -npm install -g myst-cli +npm install -g mystmd myst init myst build my-doc.md --tex ``` # Development -All packages for `mystjs` are included in this repository (a monorepo!). +All packages for `mystmd` are included in this repository (a monorepo!). ## What's inside? -`myst-cli` uses [npm](https://www.npmjs.com/) as a package manager. It includes the following packages/apps: +`mystmd` uses [npm](https://www.npmjs.com/) as a package manager. It includes the following packages/apps: + +**Command Line Tools:** + +- `mystmd` this provides CLI functionality for `myst build mystdoc.md` **Core Packages:** -- `myst-cli` this will provide CLI functionality for `myst build mystdoc.md` +- `myst-cli` this is the package that provides CLI functionality for `mystmd`, it does not export the CLI directly - `jtex` a templating library ([see docs](https://mystmd.org/jtex)) - `myst-frontmater` definitions and validation for scientific authorship/affiliation frontmatter ([see docs](https://mystmd.org/guide/frontmatter)) - `myst-config` Validation and reading of configuration files @@ -87,15 +91,15 @@ All packages for `mystjs` are included in this repository (a monorepo!). - `myst-cli-utils` some shared utils between jtex, and myst-cli - `simple-validators` validation utilities, that print all sorts of nice warnings -Each package is 100% [TypeScript](https://www.typescriptlang.org/). +Each package is 100% [TypeScript](https://www.typescriptlang.org/) and [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). ### Versioning & Publishing -`mystjs` uses [changesets](https://github.com/changesets/changesets) to document changes to this monorepo, call `npm run changeset` and follow the prompts. Later, `npm run version` will be called and then `npm run publish`. +`mystmd` uses [changesets](https://github.com/changesets/changesets) to document changes to this monorepo, call `npm run changeset` and follow the prompts. Later, `npm run version` will be called and then `npm run publish`. ### Utilities -`mystjs` is built and developed using: +`mystmd` is built and developed using: - [TypeScript](https://www.typescriptlang.org/) for static type checking - [ESLint](https://eslint.org/) for code linting @@ -106,20 +110,23 @@ Each package is 100% [TypeScript](https://www.typescriptlang.org/). To build all apps and packages, run the following command: ``` -cd mystjs +cd mystmd npm run build ``` -### Develop +## Developing -To develop all apps and packages, run the following command: +For the [mystmd](https://github.com/executablebooks/mystmd) library on GitHub, `git clone` and you can install the dependencies and then create a local copy of the library with the `npm run dev` command. -``` -cd mystjs +```shell +git clone git@github.com:executablebooks/mystmd.git +cd mystmd +npm install +npm run build npm run dev ``` -This will create a local `myst` CLI interface that you can use to develop and test locally. +This will create a local copy of `myst` for use on the command line and start various web-servers for testing. --- diff --git a/docs/accessibility-and-performance.md b/docs/accessibility-and-performance.md index e5eb79a5a..f9470b546 100644 --- a/docs/accessibility-and-performance.md +++ b/docs/accessibility-and-performance.md @@ -5,7 +5,7 @@ description: MyST sites are designed for mobile and desktop sites, accessibility ## Performance -The `mystjs` site existing, modern web-frameworks including [Remix](https://remix.run/) and [React](https://reactjs.org/). These tools come out-of-the-box with prefetching for faster navigation, smaller network payloads through modern web-bundlers, image optimization, and partial-page refresh through single-page application. We follow the [PRPL Pattern](https://web.dev/apply-instant-loading-with-prpl/)[^prpl] where possible. +The MyST Site existing, modern web-frameworks including [Remix](https://remix.run/) and [React](https://reactjs.org/). These tools come out-of-the-box with prefetching for faster navigation, smaller network payloads through modern web-bundlers, image optimization, and partial-page refresh through single-page application. We follow the [PRPL Pattern](https://web.dev/apply-instant-loading-with-prpl/)[^prpl] where possible. [^prpl]: PRPL is a pattern designed to improve performance of webpages: @@ -16,7 +16,7 @@ The `mystjs` site existing, modern web-frameworks including [Remix](https://remi As an example, try hovering over the navigation on this page (potentially with your network development tools open!), the entire page will be fetched based on your intent (i.e. hovering over the link for a moment). This includes downloading any assets for additional styling on the upcoming page. Note that many assets are shared between pages, and only the actual content is fetched (i.e. the AST and page metadata), not the full HTML page, which again makes for smaller network payloads and speed for browsing! Content is also cached if you re-visit a page. -When working locally in authoring content `mystjs` is designed to have as hot-reloads, can rebuild/rerender the site in <150ms, and has scroll-restoration so you don't loose your place. The speed of `mystjs` can dramatically improve the authoring experience as it allows you to preview changes rapidly. +When working locally MyST is designed to rebuild and rerender the site in <150ms, and has scroll-restoration so you don't loose your place. This speed can dramatically improve the authoring experience as it allows you to preview changes rapidly. The real-world deployment of your site will depend on the infrastructure that you use to serve it. See [deployment](./deployment.md) for more information on options for sharing your site. @@ -29,7 +29,7 @@ Lighthouse is a tool included in Chrome that measures accessibility, performance Lighthouse score run Sept 15, 2022 on deployed site using Curvenote's global CDN. ``` -Some of the performance and accessibility considerations we have taken in `mystjs`: +Some performance and accessibility considerations: - Semantic HTML used for articles, asides, figures, nav, and captions, including limited use of generic `div`s and `span`s where we can. - Anchor tags for all interactive content, that work when Javascript is _not_ enabled @@ -60,7 +60,7 @@ Lighthouse score run Sept 15, 2022 on deployed site, the majority of issues are ```{warning} The performance metrics above are subject to changes over time, and may differ on your computer, network connection and page analyzed. -We include these metrics on this page because (1) we have put a lot of work into performance and accessibility ๐ŸŽ‰ and (2) to let you know that as developers of `mystjs` we care about performance, accessibility, and semantic HTML that can be read by both search engine crawlers and academic indexes. +We include these metrics on this page because (1) we have put a lot of work into performance and accessibility ๐ŸŽ‰ and (2) to let you know that as MyST developers we care about performance, accessibility, and semantic HTML that can be read by both search engine crawlers and academic indexes. -If you find a place where we can improve performance in your site, please [open an issue](https://github.com/executablebooks/mystjs/issues). +If you find a place where we can improve performance in your site, please [open an issue](https://github.com/executablebooks/mystmd/issues). ``` diff --git a/docs/background.md b/docs/background.md index 6e4fec32d..5f6d5debc 100644 --- a/docs/background.md +++ b/docs/background.md @@ -1,52 +1,54 @@ --- title: Background -description: High-level discussion of the MyST ecosystem, history of mystjs, other implementations like JupyterBook and Sphinx, and explains a few decisions made in the project. +description: High-level discussion of the MyST Markdown ecosystem, history of mystmd, other implementations like JupyterBook and Sphinx, and explains past decisions. --- -This page discusses high-level questions about the MyST ecosystem, history of `mystjs`, various ecosystem implementations, and explains a few decisions made in the project. +This page discusses high-level questions about the MyST Markdown ecosystem, history of `mystmd`, various ecosystem implementations, and explains a few decisions made in the project. -## History of MyST and `mystjs` +## History of MyST Markdown and `mystmd` -MyST (Markedly Structured Text) is a markup language that builds on standard markdown and is designed to create publication-quality documents, books, presentations, and websites written entirely in Markdown. The [ExecutableBooks] team received a grant from the [Sloan Foundation](https://sloan.org) to build, enhance, and promote a new path to document creation and publishing for next-generation scientific textbooks and lectures ([Grant #9231](https://sloan.org/grant-detail/9231)). +MyST Markdown (Markedly Structured Text) is a markup language that builds on standard markdown and is designed to create publication-quality documents, books, presentations, and websites written entirely in Markdown. The [ExecutableBooks] team received a grant from the [Sloan Foundation](https://sloan.org) to build, enhance, and promote a new path to document creation and publishing for next-generation scientific textbooks and lectures ([Grant #9231](https://sloan.org/grant-detail/9231)). -The initial use case driving the development and design of MyST has been [JupyterBook], which allows you to create educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. The extensions and design of MyST is inspired by the [Sphinx] and [reStructuredText](https://docutils.sourceforge.io/rst.html) (RST) ecosystems. Jupyter Book is considered a [distribution of Sphinx](myst:jupyterbook#explain/sphinx), and builds on the Sphinx and [Docutils] Python packages. +The initial use case driving the development and design of MyST Markdown has been [JupyterBook], which allows you to create educational online textbooks and tutorials with Jupyter Notebooks and narrative content written in MyST. The extensions and design of MyST is inspired by the [Sphinx] and [reStructuredText](https://docutils.sourceforge.io/rst.html) (RST) ecosystems. Jupyter Book is considered a [distribution of Sphinx](myst:jupyterbook#explain/sphinx), and builds on the Sphinx and [Docutils] Python packages. -MyST enables rich content generation and is a powerful textual format for scientific and technical communication with potential for broad adoption in modern publishing workflows. In 2022, the Executable Books team started work to document the specification behind the markup language, called [myst-spec](https://github.com/executablebooks/myst-spec), this work has enabled other tools and implementations in the scientific ecosystem to build on MyST (e.g. [scientific authoring tools](https://curvenote.com/for/writing), and [documentation systems](https://blog.readthedocs.com/jupyter-book-read-the-docs/)). +MyST Markdown enables rich content generation and is a powerful textual format for scientific and technical communication with potential for broad adoption in modern publishing workflows. In 2022, the Executable Books team started work to document the specification behind the markup language, called [myst-spec](https://github.com/executablebooks/myst-spec), this work has enabled other tools and implementations in the scientific ecosystem to build on MyST Markdown (e.g. [scientific authoring tools](https://curvenote.com/for/writing), and [documentation systems](https://blog.readthedocs.com/jupyter-book-read-the-docs/)). -The `mystjs` ecosystem was developed as a collaboration between [Curvenote], [2i2c] and the [ExecutableBooks] team. The initial version of `mystjs` was originally release by [Curvenote] as the [Curvenote CLI](https://curvenote.com/docs/cli) under the MIT license, and later transferred to the [ExecutableBooks] team. The goal of the project is to enable the same rich content and authoring experiences that Sphinx allows for software documentation, with a focus on web-first technologies (Javascript), interactivity, accessibility, scientific references (e.g. DOIs and other PIDs), and professional PDF outputs. +The `mystmd`[^naming] command line tools were developed as a collaboration between [Curvenote], [2i2c] and the [ExecutableBooks] team. The initial version was release by [Curvenote] as the [Curvenote CLI](https://curvenote.com/docs/cli) under the MIT license, and later transferred to the [ExecutableBooks] team. The goal of the project is to enable the same rich content and authoring experiences that Sphinx allows for software documentation, with a focus on web-first technologies (Javascript), interactivity, accessibility, scientific references (e.g. DOIs and other PIDs), and professional PDF outputs. -## How do Jupyter Book and `mystjs` relate? +[^naming]: Originally `mystmd` was called `mystjs`, but was changed as we matured the command-line interfaces. -The current toolchain used by [JupyterBook] is based on [Sphinx], which is an open-source documentation system used in many software projects, especially in the Python ecosystem. `mystjs` is a similar tool to [Sphinx], however, designed for scientific and technical content. In addition to building websites, `mystjs` can also help you create scientific PDFs, Microsoft Word documents, and presentations. +## How do Jupyter Book and `mystmd` relate? -`mystjs` uses existing, modern web-frameworks in place of the [Sphinx] build system. These tools come out-of-the-box with prefetching for faster navigation, smaller network payloads through modern web-bundlers, image optimization, partial-page refresh through single-page application. Many of these features and performance improvements are difficult (if not impossible) to create inside of the [Sphinx] build system. +The current toolchain used by [JupyterBook] is based on [Sphinx], which is an open-source documentation system used in many software projects, especially in the Python ecosystem. `mystmd` is a similar tool to [Sphinx], however, designed for scientific and technical content. In addition to building websites, `mystmd` can also help you create scientific PDFs, Microsoft Word documents, and presentations. -The packages in the `mystjs` ecosystem also help power web-native extensions, such as [JupyterLab-myst], which renders MyST markup directly in JupyterLab. +`mystmd` uses existing, modern web-frameworks in place of the [Sphinx] build system. These tools come out-of-the-box with prefetching for faster navigation, smaller network payloads through modern web-bundlers, image optimization, partial-page refresh through single-page application. Many of these features and performance improvements are difficult (if not impossible) to create inside of the [Sphinx] build system. -`mystjs` can render [JupyterBook] content, however, it cannot work with custom extensions or themes developed for Sphinx. As `mystjs` continues to improve, we will ensure smooth paths for content authors to choose between these different rendering engines. +The javascript packages in the `mystmd` ecosystem also help power web-native extensions, such as [JupyterLab-myst], which renders MyST markup directly in JupyterLab. -## Can I use JupyterBook and `mystjs` together? +`mystmd` can render [JupyterBook] content, however, it cannot work with custom extensions or themes developed for Sphinx. As `mystmd` continues to improve, we will ensure smooth paths for content authors to choose between these different rendering engines. -Yes! There **is** overlap in functionality for creating websites, however, you can also use `mystjs` with your JupyterBook content to: +## Can I use JupyterBook and `mystmd` together? + +Yes! There **is** overlap in functionality for creating websites, however, you can also use `mystmd` with your JupyterBook content to: - Create a [professional PDF](./creating-pdf-documents.md) - Export to [Microsoft Word](./creating-word-documents.md) - Create a presentation - Write in JupyterLab, using [JupyterLab-myst] -If you want, you can also try a `mystjs` website to view your JupyterBook (try the [online tool provided by Curvenote](https://try.curvenote.com), to test with your JupyterBook). `mystjs` provides improved interactivity around [cross-linking content](./cross-references.md), [performance and accessibility](./accessibility-and-performance.md) improvements. +If you want, you can also try a `mystmd` website to view your JupyterBook (try the [online tool provided by Curvenote](https://try.curvenote.com), to test with your JupyterBook). `mystmd` provides improved interactivity around [cross-linking content](./cross-references.md), [performance and accessibility](./accessibility-and-performance.md) improvements. -JupyterBook and `mystjs` both use the MyST markup language for content and read Jupyter Notebooks, and we ensure that your content can be read equally by both renderers. However, no custom Sphinx extensions that you may have added to your JupyterBooks will work. If you find something that doesn't work with `mystjs` from your JupyterBook content, please [let us know on GitHub](https://github.com/executablebooks/mystjs/issues) and we will try to support it! +JupyterBook and `mystmd` both use MyST Markdown for content and read Jupyter Notebooks, and we ensure that your content can be read equally by both renderers. However, no custom Sphinx extensions that you may have added to your JupyterBooks will work. If you find something that doesn't work with `mystmd` from your JupyterBook content, please [let us know on GitHub](https://github.com/executablebooks/mystmd/issues) and we will try to support it! Jupyter Books are an excellent medium for tutorials, textbooks & software documentation but are currently less well suited to content such as blogs, lab-websites, and journal articles. Additionally, JupyterBook cannot create scientific PDFs that are submission ready. -## How do `mystjs` and Sphinx relate? +## How do `mystmd` and Sphinx relate? -[Sphinx] is an open-source documentation system used in many software projects, especially in the Python ecosystem. The Sphinx ecosystem has excellent support for Python documentation, referencing content, as well as externally providing an inventory of references known as intersphinx. You can use your `mystjs` projects with [intersphinx references](#intersphinx), and also exposes information (i.e. an `objects.inv`) to allow Sphinx documentation to reference your project. +[Sphinx] is an open-source documentation system used in many software projects, especially in the Python ecosystem. The Sphinx ecosystem has excellent support for Python documentation, referencing content, as well as externally providing an inventory of references known as intersphinx. You can use your `mystmd` projects with [intersphinx references](#intersphinx), and also exposes information (i.e. an `objects.inv`) to allow Sphinx documentation to reference your project. -At this time `mystjs` does not support software documentation[^1], as such, if your project is documenting Python software we suggest that you use Sphinx. If your project is primarily tutorials, educational textbooks (including with Jupyter Notebooks), a presentation, or scientific paper we hope that you find a better fit with `mystjs`! +At this time `mystmd` does not support software documentation[^1], as such, if your project is documenting Python software we suggest that you use Sphinx. If your project is primarily tutorials, educational textbooks (including with Jupyter Notebooks), a presentation, or scientific paper we hope that you find a better fit with `mystmd`! -[^1]: In the future, `mystjs` may offer support for Python and Javascript documentation, and if you want to contribute please reach out! +[^1]: In the future, `mystmd` may offer support for Python and Javascript documentation, and if you want to contribute please reach out! [2i2c]: https://2i2c.org/ [curvenote]: https://curvenote.com diff --git a/docs/creating-pdf-documents.md b/docs/creating-pdf-documents.md index 09a2913f5..88ca699d9 100644 --- a/docs/creating-pdf-documents.md +++ b/docs/creating-pdf-documents.md @@ -48,16 +48,16 @@ Based on the `output` field in the export list in the [frontmatter](#export-fron :class: dropdown # PDF exports require $\LaTeX$ to be installed -The default PDF renderer uses $\LaTeX$ to create PDFs, which means that to work locally you will need to [](#install-latex). `mystjs` will warn you if it cannot find a $\LaTeX$ environment, as well as forcing the build process and reporting any errors. +The default PDF renderer uses $\LaTeX$ to create PDFs, which means that to work locally you will need to [](#install-latex). A warning will occur if MyST cannot find a $\LaTeX$ environment, as well as forcing the build process and reporting any errors. ``` -The rendering process for scientific PDFs uses $\LaTeX$ and makes use of the [`jtex`](myst:jtex) templating library, to convert to $\LaTeX$ the [`myst-to-tex`](myst:myst-to-tex) packages is used. The libraries work together with `mystjs` for sharing information about [frontmatter](./frontmatter.md) (e.g. title, keywords, authors, and affiliations). +The rendering process for scientific PDFs uses $\LaTeX$ and makes use of the [`jtex`](myst:jtex) templating library, to convert to $\LaTeX$ the [`myst-to-tex`](myst:myst-to-tex) packages is used. The libraries work together for sharing information about [frontmatter](./frontmatter.md) (e.g. title, keywords, authors, and affiliations). ```{mermaid} flowchart LR A[Jupyter Notebook] --> C B[MyST Markdown] --> C - C(mystjs) --> D{AST} + C(mystmd) --> D{AST} D --> E[jtex] --> G[LaTeX] D --> F[myst-to-tex] --> G G --> H[PDF] @@ -88,7 +88,7 @@ Ensure that you download a full distribution with appropriate libraries installe ## Choosing a Template -There are currently 422 journals supported[^journals] and it is straghtforward to add new personal templates, or contribute them back to the community. +There are currently 422 journals supported[^journals] and it is straight forward to add new personal templates, or contribute them back to the community. [^journals]: As of September 15, 2022. diff --git a/docs/creating-word-documents.md b/docs/creating-word-documents.md index 68135b9bb..1bf24da3f 100644 --- a/docs/creating-word-documents.md +++ b/docs/creating-word-documents.md @@ -69,13 +69,13 @@ To fix equations in Word, use the equation toolbar to select `LaTeX` and from th ## Rendering Word with `myst-to-docx` -The rendering process for word documents uses the [`myst-to-docx`](myst:myst-to-docx) package. The library works together with `mystjs` for sharing information about [frontmatter](./frontmatter.md) (e.g. title, keywords, authors, and affiliations). +The rendering process for word documents uses the [`myst-to-docx`](myst:myst-to-docx) package. The library works together with `mystmd` for sharing information about [frontmatter](./frontmatter.md) (e.g. title, keywords, authors, and affiliations). ```{mermaid} flowchart LR A[Jupyter Notebook] --> C B[MyST Markdown] --> C - C(mystjs) --> D{AST} + C(mystmd) --> D{AST} D --> E[myst-to-docx] E --> G[docx] ``` diff --git a/docs/deployment.md b/docs/deployment.md index 6caeccaaa..25aed666a 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -76,7 +76,7 @@ jobs: with: node-version: 18.x - name: Install MyST - run: npm install -g myst-cli + run: npm install -g mystmd - name: Build HTML Assets run: myst build --html - name: Deploy to GitHub Pages diff --git a/docs/diagrams.md b/docs/diagrams.md index 9cd8be42b..7c00a2b09 100644 --- a/docs/diagrams.md +++ b/docs/diagrams.md @@ -11,7 +11,7 @@ It is possible to add [mermaid diagrams](https://mermaid-js.github.io/mermaid) u flowchart LR A[Jupyter Notebook] --> C B[MyST Markdown] --> C - C(mystjs) --> D{AST} + C(mystmd) --> D{AST} D <--> E[LaTeX] E --> F[PDF] D --> G[Word] diff --git a/docs/dropdowns-cards-and-tabs.md b/docs/dropdowns-cards-and-tabs.md index 87819acd8..ae0a68647 100644 --- a/docs/dropdowns-cards-and-tabs.md +++ b/docs/dropdowns-cards-and-tabs.md @@ -59,7 +59,7 @@ In the [Sphinx design project](https://sphinx-design.readthedocs.io/en/latest/ca - A card `footer`: Any content that comes after a line with +++. - A card `body`: Any content that comes in between ^^^ and +++. -This syntax is supported in `mystjs`, for example: +This syntax is supported in `mystmd`, for example: ```markdown :::{card} Card Title diff --git a/docs/external-references.md b/docs/external-references.md index f79d378ac..ce15917eb 100644 --- a/docs/external-references.md +++ b/docs/external-references.md @@ -1,14 +1,14 @@ --- title: External references -description: External references dynamically include content into your MyST projects, from Wikipedia, intersphinx, DOIs, RRIDs, and any other MyST projects. Allowing your documents to be rich, interactive and automatically kept up to date. +description: External references dynamically include content into your MyST Markdown projects, from Wikipedia, intersphinx, DOIs, RRIDs, and any other MyST projects. Allowing your documents to be rich, interactive and automatically kept up to date. thumbnail: ./thumbnails/external-references.png --- -MyST allows you to connect your to external [linked](wiki:Hyperlink) content like , which allow for [hover](wiki:Hovercraft)-references with external content. +MyST Markdown allows you to connect your to external [linked](wiki:Hyperlink) content like , which allow for [hover](wiki:Hovercraft)-references with external content. External references are references to structured content or documents that are outside of your project. MyST supports referencing rich content in a growing number of formats, including: -1. other `mystjs` projects, with rich cross-linking of content +1. other `mystmd` projects, with rich cross-linking of content 1. integrating directly with **Wikipedia** articles to show tooltips, 1. linking to other **Sphinx** documentation using intersphinx, 1. link to files on **GitHub** and show inline previews, @@ -116,7 +116,7 @@ Use the target in the parenthesis, which would be `myst:python#library/abc` abov ## Wikipedia Links -MyST can directly integrate with to create hover-card information directly integrated into your myst documents. The syntax follows standard markdown links, under the `wiki:` protocol followed by the page title[^1]. As with any other link, you can either follow a `[text](wiki:Page_Title)` or ``, which if no text is provided for the links will be replaced with the page title. +MyST Markdown can directly integrate with to create hover-card information directly integrated into your myst documents. The syntax follows standard markdown links, under the `wiki:` protocol followed by the page title[^1]. As with any other link, you can either follow a `[text](wiki:Page_Title)` or ``, which if no text is provided for the links will be replaced with the page title. [^1]: Replace any spaces in the page title with underscores. @@ -162,7 +162,7 @@ Wikipedia links, like `https://fr.wikipedia.org/wiki/Croissant_(viennoiserie)` w ### Issues and Pull Requests -MyST can directly link and show preview of GitHub issues and Pull Requests, for example, [#336](https://github.com/executablebooks/mystjs/issues/336) and [#87](https://github.com/executablebooks/myst-theme/pull/87). To enable this, just use a normal link to your +MyST Markdown can directly link and show preview of GitHub issues and Pull Requests, for example, [#336](https://github.com/executablebooks/mystmd/issues/336) and [#87](https://github.com/executablebooks/myst-theme/pull/87). To enable this, just use a normal link to your ```markdown [#87](https://github.com/executablebooks/myst-theme/pull/87) @@ -172,7 +172,7 @@ If you do not include children for the link, then the default text will become ` ### Linking to Code -MyST can directly integrate with links to GitHub to create hover-card information directly integrated into your MyST documents. For example, a link to the [linkTransforms](https://github.com/executablebooks/mystjs/blob/78d16ee1a/packages/myst-transforms/src/links/plugin.ts#L12-L28) plugin code shows a preview of the code. The code preview works for both multiple line numbers and highlighting [single lines](https://github.com/executablebooks/mystjs/blob/78d16ee1a/packages/myst-transforms/src/links/plugin.ts#L30), which shows the surrounding ten lines, with the referenced line highlighted. If you reference the [full file](https://github.com/executablebooks/mystjs/blob/78d16ee1a/packages/myst-transforms/src/links/plugin.ts) then the first ten lines of the file are shown in the preview. +MyST Markdown can directly integrate with links to GitHub to create hover-card information directly integrated into your MyST documents. For example, a link to the [linkTransforms](https://github.com/executablebooks/mystmd/blob/78d16ee1a/packages/myst-transforms/src/links/plugin.ts#L12-L28) plugin code shows a preview of the code. The code preview works for both multiple line numbers and highlighting [single lines](https://github.com/executablebooks/mystmd/blob/78d16ee1a/packages/myst-transforms/src/links/plugin.ts#L30), which shows the surrounding ten lines, with the referenced line highlighted. If you reference the [full file](https://github.com/executablebooks/mystmd/blob/78d16ee1a/packages/myst-transforms/src/links/plugin.ts) then the first ten lines of the file are shown in the preview. ````{important} :class: dropdown @@ -196,7 +196,7 @@ It is possible to include DOIs as external content, and they are also added as c {abbr}`RRID (Research Resource Identifiers)`s are persistent, unique identifiers for referencing a research resource, such as an antibody, plasmid, organism, or scientific tool. These are helpful for ensuring reproducibility and exact communication in scientific studies. See the [RRID website](https://scicrunch.org/resources) for more information. -MyST allows you to directly integrate with the RRID database to pull information and validate the links are correct as you are writing documents. The metadata is passed to subsequent systems (e.g. PDF documents, compatible journals and preprint servers) and helps keep your science reproducible. +MyST Markdown allows you to directly integrate with the RRID database to pull information and validate the links are correct as you are writing documents. The metadata is passed to subsequent systems (e.g. PDF documents, compatible journals and preprint servers) and helps keep your science reproducible. To create an RRID link, use the `rrid:` protocol followed by the resource identifier, for example: diff --git a/docs/glossary.md b/docs/glossary.md index 85722606e..3c47d5cdd 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -24,7 +24,7 @@ MyST is a combination of {term}`CommonMark Markdown ` and extra synt : **Command-Line Interface**: MyST is a parser and set of command-line tools for creating websites and documents. For clarity in this usage, use {term}`MyST-CLI`. [MyST-CLI](https://mystmd.org/guide) -: The MyST CLI can be used to create a website, PDF documents, and generally structure and parse a MyST project. +: The MyST Markdown CLI can be used to create a website, PDF documents, and generally structure and parse a MyST project. You can install across various package managers using `mystmd`. : Sometimes referred to simply as {term}`MyST`. [Sphinx](https://www.sphinx-doc.org) diff --git a/docs/index.md b/docs/index.md index 74716426b..ef71edc0b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -68,12 +68,12 @@ See an overview of MyST Markdown syntax with inline demos and examples. ๐Ÿ‘‹ We are glad you are here! ๐Ÿ’š -There are many ways that `mystjs` can be used with JupyterBook and Sphinx. We recommend that you read [background on `mystjs`](./background.md), which goes over how these projects overlap and work together! +There are many ways that `mystmd` can be used with JupyterBook and Sphinx. We recommend that you read [background on `mystmd`](./background.md), which goes over how these projects overlap and work together! TL;DR -: **Yes**, you can use `mystjs` with your JupyterBook! `mystjs` can create [scientific PDFs](./creating-pdf-documents.md) and can natively read the [`_toc.yml`](./table-of-contents.md) as well as all of your existing MyST Markdown content and [Jupyter Notebooks](./interactive-notebooks.ipynb). -: **Yes**, `mystjs` is compatible with [intersphinx](#intersphinx) even though it is written in Javascript not Python! -: JupyterBook and `mystjs` have **overlap** in the ability to create online books like this one. `mystjs` has some extra capabilities for [cross-references](./cross-references.md), interactivity and [performance](./accessibility-and-performance.md). +: **Yes**, you can use `mystmd` with your JupyterBook! `mystmd` can create [scientific PDFs](./creating-pdf-documents.md) and can natively read the [`_toc.yml`](./table-of-contents.md) as well as all of your existing MyST Markdown content and [Jupyter Notebooks](./interactive-notebooks.ipynb). +: **Yes**, `mystmd` is compatible with [intersphinx](#intersphinx) even though it is written in Javascript not Python! +: JupyterBook and `mystmd` have **overlap** in the ability to create online books like this one. `mystmd` has some extra capabilities for [cross-references](./cross-references.md), interactivity and [performance](./accessibility-and-performance.md). ::: ## Project Goals @@ -118,7 +118,7 @@ Read about performance ยป **Technical Goals** -- `mystjs` is a Javascript parser and command line tool for working with MyST Markdown +- `mystmd` is a Javascript parser and command line tool for working with MyST Markdown - Parse MyST into a standardized [AST](wiki:Abstract_Syntax_Tree), that follows [the MyST Spec](https://mystmd.org/spec) - Translate and render MyST into: - Modern [interactive websites](./quickstart-myst-websites.md), using React (like this website!) @@ -128,13 +128,13 @@ Read about performance ยป **Architecture** -The `mystjs` command line tool can be used to parse MyST Markdown and Jupyter Notebooks into an AST. This data can be saved as JSON, or rendered to a website (like this one!) or any number of formats including [PDF & $\LaTeX$](./creating-pdf-documents.md), [Word](./creating-word-documents.md), [React](./quickstart-myst-websites.md), or [JATS](./creating-jats-xml.md). +The `mystmd` command line tool can be used to parse MyST Markdown and Jupyter Notebooks into an AST. This data can be saved as JSON, or rendered to a website (like this one!) or any number of formats including [PDF & $\LaTeX$](./creating-pdf-documents.md), [Word](./creating-word-documents.md), [React](./quickstart-myst-websites.md), or [JATS](./creating-jats-xml.md). ```{mermaid} flowchart LR A[Jupyter Notebook] --> C B[MyST Markdown] --> C - C(mystjs) --> D{AST} + C(mystmd) --> D{AST} D <--> E[LaTeX] E --> F[PDF] D --> G[Word] @@ -152,5 +152,5 @@ For integration with **Sphinx**, use the Python implementation for MyST or Jupyt - [MyST Python Parser for Sphinx](https://myst-parser.readthedocs.io/en/latest/) - [JupyterBook](https://jupyterbook.org/) -Although many tools in the [MyST Ecosystem](https://mystmd.org) follow the same conventions and [specification](https://mystmd.org/spec), the following documentation refers only to the **Javascript** MyST CLI. +Although many tools in the [MyST Ecosystem](https://mystmd.org) follow the same conventions and [specification](https://mystmd.org/spec), the following documentation refers only to the **Javascript** MyST Markdown CLI. ``` diff --git a/docs/installing.md b/docs/installing.md index a928d7664..f7566114c 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -1,22 +1,26 @@ --- -title: Installing MyST -description: MyST is available through Node and npm, install the package with `npm install myst-cli`. +title: Installing MyST Markdown Command Line Interface +short_title: Installing MyST +description: MyST Markdown is available through Node and npm, install the package with `npm install mystmd`. --- +++ -MyST is available through [NodeJS](./installing-prerequisites.md) and the node package manager, `npm`. Node is used by Jupyter as well as many other Python packages so you may already have it installed on your _PATH_ and the following command may just work ๐Ÿคž. +The MyST Markdown Command Line Interface (CLI) is available through [NodeJS](./installing-prerequisites.md) and the node package manager, `npm`. Node is used by Jupyter as well as many other Python packages so you may already have it installed on your _PATH_ and the following command may just work ๐Ÿคž. ๐Ÿ› ๏ธ [Install NodeJS](./installing-prerequisites.md) and run the following command: ```shell -npm install -g myst-cli +npm install -g mystmd ``` -```{important} -**Note** +:::{danger} Do not use `myst-cli`! +In July 2023, we renamed the package and website to `mystmd` from `myst-cli`. Installing `myst-cli` will no longer create a `myst` command from your terminal. +::: -If you do not have `npm` installed you can look at our how to guide for [Installing NodeJS](./installing-prerequisites.md). If you have any challenges installing, please [open an issue here](https://github.com/executablebooks/mystjs/issues). +```{important} Installing Node + +If you do not have `npm` installed you can look at our how to guide for [Installing NodeJS](./installing-prerequisites.md). If you have any challenges installing, please [open an issue here](https://github.com/executablebooks/mystmd/issues). ``` This will install `myst` globally (`-g`) on your system and add a link to the main CLI tool. To see if things worked, try checking the version with: @@ -28,38 +32,23 @@ myst --version This command should print the current version of the package. If all is good, you can type `myst` again in your terminal and it will list the help with all of the options available to you. ```{note} -If you have any challenges installing, please [open an issue here](https://github.com/executablebooks/mystjs/issues). +If you have any challenges installing, please [open an issue here](https://github.com/executablebooks/mystmd/issues). ``` +++ ## Updating MyST -There are new releases of the MyST CLI every few weeks, to update to the latest version of `myst`, use: +There are new releases of the MyST Markdown CLI every few weeks, to update to the latest version of `myst`, use: ```shell -npm update -g myst-cli +npm update -g mystmd ``` -Try the `myst --version` command before and after, with an update you should be on the most up to date version (see [npm](https://npmjs.com/package/myst-cli) for the latest version!). If you are not, try `npm uninstall -g myst-cli` or without the `-g` global flag, until `myst` is no longer available on your command line. Then try installing again! +Try the `myst --version` command before and after, with an update you should be on the most up to date version (see [npm](https://npmjs.com/package/mystmd) for the latest version!). If you are not, try `npm uninstall -g mystmd` or without the `-g` global flag, until `myst` is no longer available on your command line. Then try installing again! +++ ### Dependencies for $\LaTeX$ and PDF If you are exporting to $\LaTeX$ with an open-source template specified (see all [templates](https://github.com/myst-templates)) or if you are creating a PDF you will need to install a version of [LaTeX](https://www.latex-project.org/get). - -+++ - -## Developing - -For the [mystjs](https://github.com/executablebooks/mystjs) library on GitHub, `git clone` and you can install the dependencies and then create a local copy of the library with the `npm run dev` command. - -```shell -git clone git@github.com:executablebooks/mystjs.git -cd mystjs -npm install -npm run dev -``` - -This will create a local copy of `myst` for use on the command line and start various web-servers for testing. diff --git a/docs/integrating-jupyter.md b/docs/integrating-jupyter.md index 88a24ec82..d194dcca4 100644 --- a/docs/integrating-jupyter.md +++ b/docs/integrating-jupyter.md @@ -16,7 +16,7 @@ This allows you to do some amazing things with your MyST website like: ```{attention} Integrated Jupyter Computation is hot off the press and currently limited to pages that represent complete Jupyter notebooks. -We are in active development and this feature should be considered `beta` - please help us out [report any issues that you find](https://github.com/executablebooks/mystjs/issues). +We are in active development and this feature should be considered `beta` - please help us out [report any issues that you find](https://github.com/executablebooks/mystmd/issues). Being able to connect a jupyter-based figure or output in any website page to a kernel is still work in progress - but expected very soon. The remainder of the docs below are forward looking, watch for the ๐Ÿšง icons on headings that are still work in progress. ``` @@ -245,7 +245,7 @@ Add the specific list options for custom wheel paths, etc. ## ๐Ÿšง Local Development Mode -When working on a MyST site using the `myst-cli`, using a local Jupyter server connection makes a lot of sense and speeds up development. The `local` key allows you to enable and configure a local environment without having to change the other (remote) settings in your `myst.yml` file that will be used in your final deployment. +When working on a MyST Site using `mystmd`, using a local Jupyter server connection makes a lot of sense and speeds up development. The `local` key allows you to enable and configure a local environment without having to change the other (remote) settings in your `myst.yml` file that will be used in your final deployment. Local development using can be enabled by simply adding the `local` key, which will use default server options. diff --git a/docs/myst.yml b/docs/myst.yml index 9bdf01b23..de83b86b5 100644 --- a/docs/myst.yml +++ b/docs/myst.yml @@ -1,7 +1,7 @@ version: 1 project: title: MyST Markdown - github: https://github.com/executablebooks/mystjs + github: https://github.com/executablebooks/mystmd license: code: MIT content: CC-BY-4.0 diff --git a/docs/quickstart-myst-documents.md b/docs/quickstart-myst-documents.md index 096fe9b7f..693b372c4 100644 --- a/docs/quickstart-myst-documents.md +++ b/docs/quickstart-myst-documents.md @@ -39,8 +39,8 @@ Our goal will be to try out some of the main features of `myst`, improve the str ๐Ÿ›  Download the example content, and navigate into the folder: ```bash -git clone https://github.com/executablebooks/mystjs-quickstart.git -cd mystjs-quickstart +git clone https://github.com/executablebooks/mystmd-quickstart.git +cd mystmd-quickstart ``` ::: @@ -429,7 +429,7 @@ apt install imagemagick :class: dropdown **Emojis aren't rendered in PDF ๐Ÿ˜ญ** -We are tracking [emoji support](https://github.com/executablebooks/mystjs/issues/217), if you think this feature is important and want to help out, we would love your help. ๐Ÿ’š ๐Ÿฆบ ๐Ÿชš ๐Ÿงฑ ๐Ÿ— ๐Ÿš€ +We are tracking [emoji support](https://github.com/executablebooks/mystmd/issues/217), if you think this feature is important and want to help out, we would love your help. ๐Ÿ’š ๐Ÿฆบ ๐Ÿชš ๐Ÿงฑ ๐Ÿ— ๐Ÿš€ In the screenshot below we have removed the ๐Ÿง™ emoji, which ... also works. ``` diff --git a/docs/quickstart-myst-markdown.md b/docs/quickstart-myst-markdown.md index 6a23fa369..7f7361edb 100644 --- a/docs/quickstart-myst-markdown.md +++ b/docs/quickstart-myst-markdown.md @@ -122,7 +122,7 @@ As you have seen in the links in MyST (e.g. [](./frontmatter.md)), there is info Try clicking the footnote above, you can nest information and interactive figures for the interested reader! You can help with reading comprehension by around 26% by providing information when the reader needs it!! ::: -To link to a document, for example [](./frontmatter.md), is done through a simple Markdown link `[](./frontmatter.md)`, you can put your own content in between the square brackets, but if you leave it out the link contents will be filled in with the title of the page. If you define the frontmatter on that page (i.e. the description and tooltip), you will also see that information when you hover over the link. This also works for links to Wikipedia (e.g. [Ponyies ๐Ÿด](https://en.wikipedia.org/wiki/New_Forest_pony)) as well as Github code (e.g. [](https://github.com/executablebooks/mystjs/blob/main/README.md)). +To link to a document, for example [](./frontmatter.md), is done through a simple Markdown link `[](./frontmatter.md)`, you can put your own content in between the square brackets, but if you leave it out the link contents will be filled in with the title of the page. If you define the frontmatter on that page (i.e. the description and tooltip), you will also see that information when you hover over the link. This also works for links to Wikipedia (e.g. [Ponyies ๐Ÿด](https://en.wikipedia.org/wiki/New_Forest_pony)) as well as Github code (e.g. [](https://github.com/executablebooks/mystmd/blob/main/README.md)). To create a cross-reference, you need to label a "target", like a figure, section, equation or table (or anything!!). To be referenceable, these elements can add the `label` option in many directives. To then reference the figure, use the link syntax again pointing to the label as the target `[](#my-fig)`. If you leave the title blank the default will fill in with an enumerated "Figure 1". diff --git a/docs/quickstart-myst-websites.md b/docs/quickstart-myst-websites.md index 4a1271f07..5f3880135 100644 --- a/docs/quickstart-myst-websites.md +++ b/docs/quickstart-myst-websites.md @@ -20,12 +20,12 @@ The tutorial will be brief on explaining MyST syntax, we provide a [MyST Markdow ::::{tip} :class: dropdown -## ๐Ÿ›  Install the MyST CLI +## ๐Ÿ›  Install the MyST Markdown CLI ๐Ÿ›  Install the MyST command line tools, with `node` **greater than version v16**: ```bash -npm install -g myst-cli +npm install -g mystmd ``` :::{card} Need more help? See MyST Installation Quickstart @@ -40,13 +40,13 @@ See the first quickstart tutorial for installation walk-through and installation ## ๐Ÿ›  Download quickstart content We are going to download an example project that includes a few simple markdown files and some Jupyter Notebooks. -Our goal will be to try out some of the main features of `myst` to create a website like this one, improve the structure of the metadata, share it between pages, and improve the website theme. +Our goal will be to try out some of the main features of `mystmd` to create a website like this one, improve the structure of the metadata, share it between pages, and improve the website theme. ๐Ÿ›  Download the example content, and navigate into the folder: ```bash -git clone https://github.com/executablebooks/mystjs-quickstart.git -cd mystjs-quickstart +git clone https://github.com/executablebooks/mystmd-quickstart.git +cd mystmd-quickstart ``` ::: @@ -62,7 +62,7 @@ The `myst` command is a shortcut for `myst init`, which has a few more options f ```text > myst -Welcome to the MyST CLI!! ๐ŸŽ‰ ๐Ÿš€ +Welcome to the MyST Markdown CLI!! ๐ŸŽ‰ ๐Ÿš€ myst init walks you through creating a myst.yml file. diff --git a/docs/quickstart.md b/docs/quickstart.md index 3d6ab06f4..022e0d0b3 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -22,10 +22,10 @@ The tutorials will be brief on explaining MyST syntax, but we include an [MyST M **Looking for JupyterBook docs?** The `myst` CLI is not the same as [JupyterBook](https://jupyterbook.org/), which uses the Sphinx documentation engine! -You can read about the [history of `mystjs` development](./background.md). -The content that you build is compatible between tools in the MyST ecosystem, however, this tutorial focuses on the `mystjs` tools and CLI. +You can read about the [history of `mystmd` development](./background.md). +The content that you build is compatible between tools in the MyST ecosystem, however, this tutorial focuses on the `mystmd` tools and CLI. -`mystjs` has capabilities beyond JupyterBook, for example exporting to scientific PDF documents, and you can use the two tools together! ๐Ÿ’š +`mystmd` has capabilities beyond JupyterBook, for example exporting to scientific PDF documents, and you can use the two tools together! ๐Ÿ’š ::: :::: @@ -35,9 +35,9 @@ To follow along with this quickstart tutorial on your own computer, it is helpfu > ๐Ÿ›  Throughout the tutorial, whenever you're supposed to _do_ something you will see a ๐Ÿ›  -## Installing the MyST CLI ๐Ÿ“ฆ +## Installing the MyST Markdown CLI ๐Ÿ“ฆ -The `myst-cli` is a command line interface (CLI) that provides modern tooling for technical writing, reproducible science, and creating scientific & technical websites. To get started install `myst-cli`. +`mystmd` is a command line interface (CLI) that provides modern tooling for technical writing, reproducible science, and creating scientific & technical websites. To get started, install `mystmd`. :::{tip} Prerequisites :class: dropdown @@ -50,7 +50,7 @@ You should have these programs installed: If the node ecosystem is new to you[^conda], see our getting started guides for [installing node](./installing-prerequisites.md). -[^conda]: If you have experience in Conda installations, we would _love_ your help to get the MyST install process into a form that most Pythonistas are familiar with!! See [GitHub issue](https://github.com/executablebooks/mystjs/issues/139) ๐Ÿ™ ๐Ÿ ๐Ÿš€ +[^conda]: If you have experience in Conda installations, we would _love_ your help to get the MyST install process into a form that most Pythonistas are familiar with!! See [GitHub issue](https://github.com/executablebooks/mystmd/issues/139) ๐Ÿ™ ๐Ÿ ๐Ÿš€ ::: @@ -64,19 +64,19 @@ node -v ๐Ÿ›  Install the MyST command line tools: ```bash -npm install -g myst-cli +npm install -g mystmd ``` -If you have any problems, see [installing MyST](./installing.md) and or [open an issue here](https://github.com/executablebooks/mystjs/issues/new?assignees=&labels=bug&template=bug_report.yml). ๐Ÿ› +If you have any problems, see [installing MyST](./installing.md) and or [open an issue here](https://github.com/executablebooks/mystmd/issues/new?assignees=&labels=bug&template=bug_report.yml). ๐Ÿ› :::{note} :class: dropdown **Updating MyST** -There are new releases of the MyST CLI every few weeks, to update to the latest version of `myst`, use: +There are new releases of the MyST Markdown CLI every few weeks, to update to the latest version of `myst`, use: ```shell -npm update -g myst-cli +npm update -g mystmd ``` ::: @@ -89,11 +89,11 @@ In it's initial state, the project is **not** a good example of how to use MyST, ๐Ÿ›  Download the example content[^no-git], and navigate into the folder: ```bash -git clone https://github.com/executablebooks/mystjs-quickstart.git -cd mystjs-quickstart +git clone https://github.com/executablebooks/mystmd-quickstart.git +cd mystmd-quickstart ``` -[^no-git]: If you aren't familiar with git, it isn't required for this tutorial, you can download the zip file with the contents from the [quickstart repository](https://github.com/executablebooks/mystjs-quickstart). +[^no-git]: If you aren't familiar with git, it isn't required for this tutorial, you can download the zip file with the contents from the [quickstart repository](https://github.com/executablebooks/mystmd-quickstart). ## Go through the tutorials ๐Ÿš€ diff --git a/docs/table-of-contents.md b/docs/table-of-contents.md index 943b6cdf2..562277834 100644 --- a/docs/table-of-contents.md +++ b/docs/table-of-contents.md @@ -91,7 +91,7 @@ parts: ## Nesting of Files in URLs -You can have any level of nesting in a file-system of your project, however, when it is displayed in the URL in `mystjs`, these nesting will be flattened to have a single โ€œslugโ€ that is contained in the project. +You can have any level of nesting in a file-system of your project, however, when it is displayed in the URL in `mystmd`, these nesting will be flattened to have a single โ€œslugโ€ that is contained in the project. - `project/folder2/01_my_article.md` becomes `project/my-article` diff --git a/package-lock.json b/package-lock.json index 7c34b7a6e..2a6051723 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,5 +1,5 @@ { - "name": "mystjs", + "name": "mystmd", "lockfileVersion": 3, "requires": true, "packages": { @@ -7905,6 +7905,10 @@ "resolved": "packages/myst-transforms", "link": true }, + "node_modules/mystmd": { + "resolved": "packages/mystmd", + "link": true + }, "node_modules/nanoid": { "version": "4.0.2", "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-4.0.2.tgz", @@ -12542,6 +12546,16 @@ "@types/katex": "^0.14.0" } }, + "packages/mystmd": { + "version": "0.0.1", + "license": "MIT", + "bin": { + "myst": "myst.cjs" + }, + "devDependencies": { + "myst-cli": "^1.0.0" + } + }, "packages/simple-validators": { "version": "1.0.0", "license": "MIT", diff --git a/packages/citation-js-utils/CHANGELOG.md b/packages/citation-js-utils/CHANGELOG.md index 3a4fec26c..681980a7b 100644 --- a/packages/citation-js-utils/CHANGELOG.md +++ b/packages/citation-js-utils/CHANGELOG.md @@ -34,7 +34,7 @@ ### Patch Changes -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd ## 0.0.10 diff --git a/packages/citation-js-utils/package.json b/packages/citation-js-utils/package.json index 8000a610b..8cd16a2c3 100644 --- a/packages/citation-js-utils/package.json +++ b/packages/citation-js-utils/package.json @@ -19,7 +19,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "keywords": [ "citation-js" @@ -27,9 +27,9 @@ "author": "Rowan Cockett ", "license": "MIT", "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/citation-js-utils", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/citation-js-utils", "engines": { "node": ">=12", "npm": ">=6" diff --git a/packages/jats-to-myst/package.json b/packages/jats-to-myst/package.json index d02c17c33..1ab4aa03f 100644 --- a/packages/jats-to-myst/package.json +++ b/packages/jats-to-myst/package.json @@ -3,7 +3,7 @@ "version": "1.0.2", "description": "Read JATS and convert to MyST AST", "author": "Rowan Cockett ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/jats-to-myst", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/jats-to-myst", "license": "MIT", "type": "module", "exports": "./dist/index.js", @@ -20,7 +20,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rm -rf dist", @@ -32,7 +32,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "doi-utils": "^2.0.0", diff --git a/packages/jtex/CHANGELOG.md b/packages/jtex/CHANGELOG.md index dea2ede8f..b0bfcbd29 100644 --- a/packages/jtex/CHANGELOG.md +++ b/packages/jtex/CHANGELOG.md @@ -201,7 +201,7 @@ ### Patch Changes -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd - 615c1441: Jtex can now be used to pre-render word templates - 615c1441: Sessions are now aware of their build path (making things more consistent) For example, change the template location to the site working directory. diff --git a/packages/jtex/docs/create-a-beamer-template.md b/packages/jtex/docs/create-a-beamer-template.md index 80d8055fe..025747d5b 100644 --- a/packages/jtex/docs/create-a-beamer-template.md +++ b/packages/jtex/docs/create-a-beamer-template.md @@ -4,7 +4,7 @@ description: jtex can render to beamer templates, and needs an additional flag t --- ```{danger} -Beamer templating is currently in development, and cannot yet be accessed through the command line tools. Please see [github](https://github.com/executablebooks/mystjs/issues/97) for updates. +Beamer templating is currently in development, and cannot yet be accessed through the command line tools. Please see [github](https://github.com/executablebooks/mystmd/issues/97) for updates. ``` Beamer slides are created in MyST by separating them out into blocks, denoted by the `+++` markup with optional metadata in JSON. diff --git a/packages/jtex/docs/myst.yml b/packages/jtex/docs/myst.yml index eab62127d..8c3614c9d 100644 --- a/packages/jtex/docs/myst.yml +++ b/packages/jtex/docs/myst.yml @@ -1,7 +1,7 @@ version: 1 project: title: JTeX - github: https://github.com/executablebooks/mystjs/tree/main/packages/jtex + github: https://github.com/executablebooks/mystmd/tree/main/packages/jtex license: MIT subject: Jinja LaTeX Templates site: diff --git a/packages/jtex/package.json b/packages/jtex/package.json index 60663de62..5a9a84de9 100644 --- a/packages/jtex/package.json +++ b/packages/jtex/package.json @@ -14,7 +14,7 @@ "clean": "rimraf dist _build", "unlink": "npm uninstall -g jtex;", "link": "npm run unlink; npm link;", - "dev": "npm run link && esbuild src/cli/index.ts --bundle --outfile=dist/jtex.js --platform=node --watch", + "dev": "npm run link && esbuild src/cli/index.ts --bundle --outfile=dist/jtex.cjs --platform=node --watch", "lint": "npm run copy:version && eslint -c .eslintrc.cjs src/**/*.ts tests/**/*.ts", "lint:format": "npm run copy:version && prettier --check \"src/**/*.ts\" \"tests/**/*.ts\"", "test": "vitest run", @@ -25,7 +25,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "keywords": [ "jtex", @@ -36,9 +36,9 @@ "author": "Rowan Cockett ", "license": "MIT", "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/jtex", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/jtex", "engines": { "node": ">=12", "npm": ">=6" diff --git a/packages/markdown-it-myst/package.json b/packages/markdown-it-myst/package.json index 06305c330..c36616432 100644 --- a/packages/markdown-it-myst/package.json +++ b/packages/markdown-it-myst/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "markdown-it tokenizer for MyST roles and directives", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/markdown-it-myst", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/markdown-it-myst", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "js-yaml": "^4.1.0", diff --git a/packages/myst-cli-utils/CHANGELOG.md b/packages/myst-cli-utils/CHANGELOG.md index f31cc7ab0..f43be0c64 100644 --- a/packages/myst-cli-utils/CHANGELOG.md +++ b/packages/myst-cli-utils/CHANGELOG.md @@ -48,7 +48,7 @@ ### Patch Changes -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd ## 0.0.5 diff --git a/packages/myst-cli-utils/package.json b/packages/myst-cli-utils/package.json index c82cb890d..7d953aa12 100644 --- a/packages/myst-cli-utils/package.json +++ b/packages/myst-cli-utils/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "Utils for logging, error messages and session management", "author": "Rowan Cockett ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-cli-utils", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-cli-utils", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "chalk": "^5.2.0", diff --git a/packages/myst-cli/CHANGELOG.md b/packages/myst-cli/CHANGELOG.md index 495ea3350..7ab0288b5 100644 --- a/packages/myst-cli/CHANGELOG.md +++ b/packages/myst-cli/CHANGELOG.md @@ -760,7 +760,7 @@ - 17daf15e: Introduce GithubTransformer for file links. - 88666aee: Deprecate unified exports from `mystjs` -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd - cfb1307b: Relative paths in config should be '.' not '' - 615c1441: Sessions are now aware of their build path (making things more consistent) For example, change the template location to the site working directory. diff --git a/packages/myst-cli/docs/myst.yml b/packages/myst-cli/docs/myst.yml index a14a67f69..10f0916a7 100644 --- a/packages/myst-cli/docs/myst.yml +++ b/packages/myst-cli/docs/myst.yml @@ -1,10 +1,10 @@ version: 1 project: title: MyST Markdown CLI - github: https://github.com/executablebooks/mystjs/tree/main/packages/myst-cli + github: https://github.com/executablebooks/mystmd/tree/main/packages/myst-cli license: MIT - subject: MyST CLI + subject: MyST Markdown CLI site: - title: MyST CLI + title: MyST Markdown CLI domains: - mystmd-cli.curve.space diff --git a/packages/myst-cli/docs/reference.md b/packages/myst-cli/docs/reference.md index 0815d9084..6c6c9d87a 100644 --- a/packages/myst-cli/docs/reference.md +++ b/packages/myst-cli/docs/reference.md @@ -1,5 +1,5 @@ --- -title: MyST CLI Reference +title: MyST Markdown CLI Reference --- (myst-init)= diff --git a/packages/myst-cli/package.json b/packages/myst-cli/package.json index f956d18b3..ff3c88e0a 100644 --- a/packages/myst-cli/package.json +++ b/packages/myst-cli/package.json @@ -20,27 +20,25 @@ ], "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, - "homepage": "https://github.com/executablebooks/mystjs", + "homepage": "https://github.com/executablebooks/mystmd", "bin": { "myst": "./dist/myst.cjs" }, "scripts": { "clean": "rimraf dist", "copy:version": "echo \"const version = '\"$npm_package_version\"';\nexport default version;\" > src/version.ts", - "unlink": "npm uninstall -g myst-cli", - "link": "npm run unlink; npm link;", - "dev": "npm run link && concurrently \"tsc -w --preserveWatchOutput --outDir dist -p .\" \"esbuild src/cli/index.ts --bundle --outfile=dist/myst.js --platform=node --external:fsevents --watch\"", + "dev": "concurrently \"tsc -w --preserveWatchOutput --outDir dist -p .\" \"esbuild src/cli/index.ts --bundle --outfile=../mystmd/myst.cjs --platform=node --external:fsevents --watch\"", "lint": "npm run copy:version; eslint \"src/**/*.ts\" -c .eslintrc.cjs", "lint:format": "npm run copy:version; prettier --check \"src/**/*.ts\"", - "test": "npm run copy:version; npm run link; vitest run", - "test:watch": "npm run copy:version; npm run link; vitest watch", + "test": "npm run copy:version; vitest run", + "test:watch": "npm run copy:version; vitest watch", "build:esm": "tsc --project ./tsconfig.json --module es2015 --outDir dist --declaration", - "build:cli": "esbuild src/cli/index.ts --bundle --outfile=dist/myst.cjs --platform=node --external:fsevents", + "build:cli": "esbuild src/cli/index.ts --bundle --outfile=../mystmd/myst.cjs --platform=node --external:fsevents", "build": "npm-run-all -l clean copy:version -p build:esm build:cli" }, "engines": { diff --git a/packages/myst-cli/src/build/init.ts b/packages/myst-cli/src/build/init.ts index b945c0c73..cecea7139 100644 --- a/packages/myst-cli/src/build/init.ts +++ b/packages/myst-cli/src/build/init.ts @@ -40,7 +40,7 @@ export type InitOptions = { }; const WELCOME = () => ` -${chalk.bold.yellowBright.italic('Welcome to the MyST CLI!!')} ๐ŸŽ‰ ๐Ÿš€ +${chalk.bold.yellowBright.italic('Welcome to the MyST Markdown CLI!!')} ๐ŸŽ‰ ๐Ÿš€ ${chalk.bold.green('myst init')} walks you through creating a ${chalk.bold.blue('myst.yml')} file. diff --git a/packages/myst-cli/src/process/mdast.ts b/packages/myst-cli/src/process/mdast.ts index 1ddd1f7ab..395b4aa68 100644 --- a/packages/myst-cli/src/process/mdast.ts +++ b/packages/myst-cli/src/process/mdast.ts @@ -61,7 +61,7 @@ const LINKS_SELECTOR = 'link,card,linkBlock'; const htmlHandlers = { comment(h: any, node: any) { // Prevents HTML comments from showing up as text in web - // TODO: Remove once this is landed in mystjs + // TODO: Remove once this is landed in myst-parser const result = h(node, 'comment'); (result as any).value = node.value; return result; diff --git a/packages/myst-cli/tests/basic-md-and-config/myst.yml b/packages/myst-cli/tests/basic-md-and-config/myst.yml index b915d19eb..fa85501c7 100644 --- a/packages/myst-cli/tests/basic-md-and-config/myst.yml +++ b/packages/myst-cli/tests/basic-md-and-config/myst.yml @@ -5,7 +5,7 @@ project: # description: keywords: [] authors: [] - github: https://github.com/executablebooks/mystjs + github: https://github.com/executablebooks/mystmd # bibliography: [] site: template: book-theme diff --git a/packages/myst-common/CHANGELOG.md b/packages/myst-common/CHANGELOG.md index 6b323609e..8934cf2a7 100644 --- a/packages/myst-common/CHANGELOG.md +++ b/packages/myst-common/CHANGELOG.md @@ -82,7 +82,7 @@ ### Patch Changes -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd - 3fba7cb7: Modify extractPart to no longer support tags ## 0.0.4 diff --git a/packages/myst-config/CHANGELOG.md b/packages/myst-config/CHANGELOG.md index 496521b7e..07aa98514 100644 --- a/packages/myst-config/CHANGELOG.md +++ b/packages/myst-config/CHANGELOG.md @@ -114,7 +114,7 @@ ### Patch Changes -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd - Updated dependencies [184ad9f9] - Updated dependencies [615c1441] - myst-frontmatter@0.0.3 diff --git a/packages/myst-config/package.json b/packages/myst-config/package.json index 0bc28e5cf..a7eb92af6 100644 --- a/packages/myst-config/package.json +++ b/packages/myst-config/package.json @@ -2,9 +2,9 @@ "name": "myst-config", "version": "1.0.0", "license": "MIT", - "description": "Project and site config types and validation for the mystjs ecosystem", + "description": "Project and site config types and validation for the mystmd ecosystem", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-config", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-config", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -16,7 +16,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -28,7 +28,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "myst-frontmatter": "^1.0.0", diff --git a/packages/myst-directives/package.json b/packages/myst-directives/package.json index d9e724495..d2076b98f 100644 --- a/packages/myst-directives/package.json +++ b/packages/myst-directives/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "Default directive definitions for MyST", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-directives", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-directives", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -27,7 +27,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "js-yaml": "^4.1.0", diff --git a/packages/myst-ext-card/README.md b/packages/myst-ext-card/README.md index f0209dd62..aaf751a59 100644 --- a/packages/myst-ext-card/README.md +++ b/packages/myst-ext-card/README.md @@ -1,3 +1,3 @@ # myst-ext-card -`mystjs` extension for `card` directive +`mystmd` extension for `card` directive diff --git a/packages/myst-ext-card/package.json b/packages/myst-ext-card/package.json index 27d6b23f6..6ac919469 100644 --- a/packages/myst-ext-card/package.json +++ b/packages/myst-ext-card/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "MyST extension for card directive", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-ext-card", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-ext-card", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "myst-common": "^1.0.0" diff --git a/packages/myst-ext-exercise/README.md b/packages/myst-ext-exercise/README.md index c1a0bbc2a..be4310100 100644 --- a/packages/myst-ext-exercise/README.md +++ b/packages/myst-ext-exercise/README.md @@ -1,3 +1,3 @@ # myst-ext-exercise -`mystjs` extension for `exercise` directive +`mystmd` extension for `exercise` directive diff --git a/packages/myst-ext-exercise/package.json b/packages/myst-ext-exercise/package.json index 239b8081b..11fda6e2d 100644 --- a/packages/myst-ext-exercise/package.json +++ b/packages/myst-ext-exercise/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "MyST extension for exercise", "author": "Rowan Cockett ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-ext-exercise", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-ext-exercise", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "myst-common": "^1.0.0" diff --git a/packages/myst-ext-grid/README.md b/packages/myst-ext-grid/README.md index 4f015a7d1..922447bec 100644 --- a/packages/myst-ext-grid/README.md +++ b/packages/myst-ext-grid/README.md @@ -1,3 +1,3 @@ # myst-ext-grid -`mystjs` extension for `grid` directive +`mystmd` extension for `grid` directive diff --git a/packages/myst-ext-grid/package.json b/packages/myst-ext-grid/package.json index 613cd1dc5..ace05fb2f 100644 --- a/packages/myst-ext-grid/package.json +++ b/packages/myst-ext-grid/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "MyST extension for grid directive", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-ext-grid", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-ext-grid", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "myst-common": "^1.0.0" diff --git a/packages/myst-ext-proof/README.md b/packages/myst-ext-proof/README.md index 52fd84065..2906a04d3 100644 --- a/packages/myst-ext-proof/README.md +++ b/packages/myst-ext-proof/README.md @@ -1,3 +1,3 @@ # myst-ext-proof -`mystjs` extension for `proof` directive +`mystmd` extension for `proof` directive diff --git a/packages/myst-ext-proof/package.json b/packages/myst-ext-proof/package.json index 8a3f1a815..d30c215ac 100644 --- a/packages/myst-ext-proof/package.json +++ b/packages/myst-ext-proof/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "MyST extension for proofs", "author": "Rowan Cockett ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-ext-proof", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-ext-proof", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "myst-common": "^1.0.0" diff --git a/packages/myst-ext-reactive/README.md b/packages/myst-ext-reactive/README.md index f0209dd62..aaf751a59 100644 --- a/packages/myst-ext-reactive/README.md +++ b/packages/myst-ext-reactive/README.md @@ -1,3 +1,3 @@ # myst-ext-card -`mystjs` extension for `card` directive +`mystmd` extension for `card` directive diff --git a/packages/myst-ext-reactive/package.json b/packages/myst-ext-reactive/package.json index 80074e3c4..163e8687b 100644 --- a/packages/myst-ext-reactive/package.json +++ b/packages/myst-ext-reactive/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "MyST extension for reactive variables", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-ext-reactive", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-ext-reactive", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "myst-common": "^1.0.0" diff --git a/packages/myst-ext-tabs/README.md b/packages/myst-ext-tabs/README.md index 41a8051d5..4de19c5f6 100644 --- a/packages/myst-ext-tabs/README.md +++ b/packages/myst-ext-tabs/README.md @@ -1,3 +1,3 @@ # myst-ext-tabs -`mystjs` extension for `tab-set` and `tab-item` directives +`mystmd` extension for `tab-set` and `tab-item` directives diff --git a/packages/myst-ext-tabs/package.json b/packages/myst-ext-tabs/package.json index 4270fe922..ab0dbfa6e 100644 --- a/packages/myst-ext-tabs/package.json +++ b/packages/myst-ext-tabs/package.json @@ -5,7 +5,7 @@ "license": "MIT", "description": "MyST extension for tab-set and tab-item directive", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-ext-tabs", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-ext-tabs", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "myst-common": "^1.0.0" diff --git a/packages/myst-frontmatter/CHANGELOG.md b/packages/myst-frontmatter/CHANGELOG.md index 3c819d7c7..9e72a946f 100644 --- a/packages/myst-frontmatter/CHANGELOG.md +++ b/packages/myst-frontmatter/CHANGELOG.md @@ -90,7 +90,7 @@ ### Patch Changes -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd - 615c1441: Sessions are now aware of their build path (making things more consistent) For example, change the template location to the site working directory. diff --git a/packages/myst-frontmatter/package.json b/packages/myst-frontmatter/package.json index 6ddcc0475..40fe26ab0 100644 --- a/packages/myst-frontmatter/package.json +++ b/packages/myst-frontmatter/package.json @@ -3,9 +3,9 @@ "version": "1.0.1", "sideEffects": false, "license": "MIT", - "description": "Frontmatter types and validation for the mystjs ecosystem", + "description": "Frontmatter types and validation for the mystmd ecosystem", "author": "Franklin Koch ", - "homepage": "https://github.com/executablebooks/mystjs/tree/main/packages/myst-frontmatter", + "homepage": "https://github.com/executablebooks/mystmd/tree/main/packages/myst-frontmatter", "type": "module", "exports": "./dist/index.js", "types": "./dist/index.d.ts", @@ -17,7 +17,7 @@ }, "repository": { "type": "git", - "url": "git+https://github.com/executablebooks/mystjs.git" + "url": "git+https://github.com/executablebooks/mystmd.git" }, "scripts": { "clean": "rimraf dist", @@ -29,7 +29,7 @@ "build": "npm-run-all -l clean -p build:esm" }, "bugs": { - "url": "https://github.com/executablebooks/mystjs/issues" + "url": "https://github.com/executablebooks/mystmd/issues" }, "dependencies": { "credit-roles": "^2.0.0", diff --git a/packages/myst-parser/CHANGELOG.md b/packages/myst-parser/CHANGELOG.md index e7c365b6a..25d93c12d 100644 --- a/packages/myst-parser/CHANGELOG.md +++ b/packages/myst-parser/CHANGELOG.md @@ -196,6 +196,6 @@ - 88666aee: Deprecate unified exports from `mystjs` - a9110bff: Add positions to nodes and update tests -- 184ad9f9: Move to https://github.com/executablebooks/mystjs +- 184ad9f9: Move to https://github.com/executablebooks/mystmd - a9110bff: Update line-number logic for code-block to come inline with sphinx - a9110bff: Pass image height to image token if it exists diff --git a/packages/myst-parser/docs/_toc.yml b/packages/myst-parser/docs/_toc.yml index 6b804be20..085e0a721 100644 --- a/packages/myst-parser/docs/_toc.yml +++ b/packages/myst-parser/docs/_toc.yml @@ -19,12 +19,12 @@ parts: - file: features/footnotes - file: features/definitions - file: features/tasks - - caption: Using the mystjs Library + - caption: Using the Library chapters: - file: consuming/basic - file: consuming/mdast - file: consuming/advanced - - caption: Extending MyST with mystjs + - caption: Extending MyST chapters: - file: extending/roles - file: extending/directives diff --git a/packages/myst-parser/docs/consuming/advanced.md b/packages/myst-parser/docs/consuming/advanced.md index 2146bbc77..4d8559f39 100644 --- a/packages/myst-parser/docs/consuming/advanced.md +++ b/packages/myst-parser/docs/consuming/advanced.md @@ -20,7 +20,7 @@ src/ โ””โ”€โ”€ utils.ts ``` -## Using `mystjs` +## Using `myst-parser` There are two ways to use the library, you can use the `MyST` wrapper, which creates a `MarkdownIt` tokenizer for you: @@ -53,7 +53,6 @@ For installing the package locally, you will need [node](https://nodejs.org/) an Once you have `npm` installed globally, navigate into this project folder and install the dependencies: ```bash -cd mystjs npm install npm run start # Start a development server to play with the library! ๐Ÿš€ ``` @@ -67,16 +66,16 @@ This outputs to the `dist` folder, and also includes all type definitions (`*.d. The command `npm run test` runs the tests, these are mostly based on the [fixtures](fixtures) folder. You can also use `npm run test:watch` to run on any file changes. -The command `npm run start` starts a server for manually testing and playing with `mystjs`, this uses a in-memory bundle of what would go in the `dist` folder. +The command `npm run start` starts a server for manually testing and playing with MyST, this uses a in-memory bundle of what would go in the `dist` folder. Note that this does not actually build the library! ## Typescript -`mystjs` uses Typescript in `strict` mode and `noImplicitAny`. The types are distributed with the package. +`myst-parser` uses Typescript in `strict` mode and `noImplicitAny`. The types are distributed with the package. ## Build Targets -The package create a `dist` folder and transpiles all code from Typescript to Javascript. +The package create a `dist` folder and transpile all code from Typescript to Javascript. The main library can run in both the browser and in node, however, another file `myst.ts` is used to attached the global `MyST` variable to the `window`. This file `myst.min.js` is what should be distributed when using scripts in HTML. diff --git a/packages/myst-parser/docs/consuming/basic.md b/packages/myst-parser/docs/consuming/basic.md index 47ad39adf..0d0e5866b 100644 --- a/packages/myst-parser/docs/consuming/basic.md +++ b/packages/myst-parser/docs/consuming/basic.md @@ -1,6 +1,6 @@ # Basic Usage -`mystjs` allows you to parse and render MyST in both the browser or in a node environment. The parse creates an abstract syntax tree (AST) +`myst-parser` allows you to parse and render MyST in both the browser or in a node environment. The parse creates an abstract syntax tree (AST) ### Using a Browser @@ -29,7 +29,7 @@ If you are building the project on your own, please follow the [](developer) and ### Using Node ```bash -npm install mystjs +npm install myst-parser ``` You can now import (or `require`) the library. diff --git a/packages/myst-parser/docs/index.md b/packages/myst-parser/docs/index.md index 89be2dc54..d578b720d 100644 --- a/packages/myst-parser/docs/index.md +++ b/packages/myst-parser/docs/index.md @@ -1,13 +1,13 @@ -# mystjs +# myst-parser -[![mystjs on npm](https://img.shields.io/npm/v/mystjs.svg)](https://www.npmjs.com/package/mystjs) -[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/executablebooks/mystjs/blob/master/LICENSE) -[![CI](https://github.com/executablebooks/mystjs/workflows/CI/badge.svg)](https://github.com/executablebooks/mystjs/actions) -[![docs](https://github.com/executablebooks/mystjs/workflows/docs/badge.svg)](https://executablebooks.github.io/mystjs) +[![myst-parser on npm](https://img.shields.io/npm/v/myst-parser.svg)](https://www.npmjs.com/package/myst-parser) +[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/executablebooks/mystmd/blob/master/LICENSE) +[![CI](https://github.com/executablebooks/mystmd/workflows/CI/badge.svg)](https://github.com/executablebooks/mystmd/actions) +[![docs](https://github.com/executablebooks/mystmd/workflows/docs/badge.svg)](https://executablebooks.github.io/myst-parser) {abbr}`MyST (Markedly Structured Text)` is a flavor of markdown inspired from the Sphinx ecosystem and {abbr}`RST (reStructuredText)`. -Any [CommonMark](https://commonmark.org/) markdown (such as [Jupyter Notebook](https://jupyter.org) markdown) is natively supported by the MyST parser. The goal of MyST _javascript_ parser ([mystjs](https://github.com/executablebooks/mystjs)) is to have overlap with Sphinx ecosystem and {abbr}`RST (reStructuredText)` and provide a flexible parser and renderer that can be used with other content workflows. +Any [CommonMark](https://commonmark.org/) markdown (such as [Jupyter Notebook](https://jupyter.org) markdown) is natively supported by the MyST parser. The goal of MyST _javascript_ parser ([myst-parser](https://github.com/executablebooks/mystmd)) is to have overlap with Sphinx ecosystem and {abbr}`RST (reStructuredText)` and provide a flexible parser and renderer that can be used with other content workflows. ```{important} For integration with **Sphinx**, use the Python reference implementation for MyST parser, which can be found at: @@ -17,11 +17,11 @@ For integration with **Sphinx**, use the Python reference implementation for MyS The following documentation refers only to the Javascript MyST parser. ``` -The focus of `mystjs` is on components that are useful in rendering books, papers & reorts. This project is associated with [JupyterBook](https://jupyterbook.org/) and maintained by the [Executable Books Community](https://executablebooks.org/). +The focus of `mystmd` is on components that are useful in rendering books, papers & reports. This project is associated with [JupyterBook](https://jupyterbook.org/) and maintained by the [Executable Books Community](https://executablebooks.org/). ## Package Responsibilities -The `mystjs` package provides a Javascript implementation of the [MyST](https://myst-parser.readthedocs.io) parser, with the many of the standard directives and roles included. +The `myst-parser` package provides a Javascript implementation of the [MyST](https://myst-parser.readthedocs.io) parser, with the many of the standard directives and roles included. - Parse MyST flavored markdown, which includes directives, roles, and block elements - Export a Markdown Abstract Syntax Tree (`mdast`) that is tested against the MyST specification @@ -32,7 +32,7 @@ The `mystjs` package provides a Javascript implementation of the [MyST](https:// ## Supported Syntax -- Commonmark Markdown +- CommonMark Markdown - Admonitions (callouts) - References and citations - Figures, with cross-references @@ -41,7 +41,7 @@ The `mystjs` package provides a Javascript implementation of the [MyST](https:// ## Design Choices and Related Packages -The `mystjs` package currently uses `markdown-it` for parsing markdown. This includes packages that are elsewhere in the executablebooks community including: +The `myst-parser` package currently uses `markdown-it` for parsing markdown. This includes packages that are elsewhere in the executablebooks community including: - [markdown-it-docutils](https://github.com/executablebooks/markdown-it-docutils) - directives and roles - [markdown-it-dollarmath](https://github.com/executablebooks/markdown-it-dollarmath) - Math extensions to support inline $\LaTeX$ math surrounded by `$` @@ -51,5 +51,5 @@ The `mystjs` package currently uses `markdown-it` for parsing markdown. This inc The package also includes community supported markdown-it plugins (e.g. `markdown-it-footnote`, and others as necessary). ```{note} -`mystjs` may adopt portions of the [unified](https://unifiedjs.com/) ecosystem in the future, but will continue to support basic `markdown-it` parsing as this is required in extending markdown parsers in, for example, [VSCode](https://github.com/executablebooks/myst-vs-code). +`myst-parser` may adopt portions of the [unified](https://unifiedjs.com/) ecosystem in the future, but will continue to support basic `markdown-it` parsing as this is required in extending markdown parsers in, for example, [VSCode](https://github.com/executablebooks/myst-vs-code). ``` diff --git a/packages/myst-parser/index.html b/packages/myst-parser/index.html index fdfb651f7..f29f017cc 100644 --- a/packages/myst-parser/index.html +++ b/packages/myst-parser/index.html @@ -31,7 +31,7 @@