diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 7780a713b..644e632f2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -26,7 +26,7 @@ jobs:
runs-on: ubuntu-latest
strategy:
matrix:
- node: ['16', '18']
+ node: ['16', '18', '20']
name: Testing on node ${{ matrix.node }}
steps:
- uses: actions/checkout@v3
diff --git a/README.md b/README.md
index a20ff6677..cce5a2aec 100644
--- a/README.md
+++ b/README.md
@@ -25,11 +25,29 @@ See the [documentation](https://mystmd.org/guide).
## Get Started
-The MyST Markdown CLI is available through Node and NPM:
+Ensure that you have an updated version of Node installed ():
```bash
+node -v
+>> v20.4.0
+```
+
+The MyST Markdown CLI is available through NPM, PyPI and Conda:
+
+```bash
+# Using npm, yarn, or pnpm
npm install -g mystmd
+# Or using PyPI
+pip install mystmd
+# Or using Conda / Mamba
+conda install mystmd -c conda-forge
+```
+
+Usage:
+
+```bash
myst init
+myst start
myst build my-doc.md --tex
```
diff --git a/docs/installing-prerequisites.md b/docs/installing-prerequisites.md
index 355950d15..aeb380435 100644
--- a/docs/installing-prerequisites.md
+++ b/docs/installing-prerequisites.md
@@ -1,41 +1,34 @@
---
title: Installing NodeJS
-description: The MyST Command Line Interface (CLI) is built on NodeJS, a Javascript runtime that is widely used in many projects including well-known Python projects such as Jupyter Lab. MyST can be installed by the package manager npm.
+description: The MyST Command Line Interface (CLI) is built on NodeJS, a Javascript runtime that is widely used in many projects including well-known Python projects such as Jupyter Lab. MyST can be installed by the package manager npm, PyPI, Conda or Mamba.
---
-+++
+The MyST Command Line Interface (CLI) is built on [NodeJS](https://nodejs.org/en/about) (`node`), a Javascript runtime that is widely used in many projects including well-known Python projects such as Jupyter Lab. `node` comes with its own package manager called `npm`.
-The MyST Command Line Interface (CLI) is built on [NodeJS](https://nodejs.org/en/about/) (`nodejs`), a Javascript runtime that is widely used in many projects including well-known Python projects such as Jupyter Lab. `node` comes with its own package manager called `npm`.
+There are a number of ways to install `node` and you can choose one that is suitable depending on your platform and preferences.
-There are a number of ways to install `nodejs` and you can choose one that is suitable depending on your platform and preferences.
+:::{important} Node Versions
-````{important}
-**Node Versions**
+MyST currently supports `node` v16, v18 and v20. Note that odd-numbered releases of `node` are not long-lived and you should prefer even-numbered releases when installing (see [Node release schedule](https://nodejs.org/en/about/previous-releases)).
+:::
-MyST currently supports `nodejs` v16 and v18. Note that odd-numbered releases of `nodejs` are not long-lived and you should prefer even-numbered releases when installing.
-````
-
-Following any of the install methods below, verify your installation and ensure that `node` and `npm` are available on your system *PATH* by opening a new terminal window or command line prompt and typing:
+Following any of the install methods below, verify your installation and ensure that `node` and `npm` are available on your system _PATH_ by opening a new terminal window or command line prompt and typing:
```text
% node -v
-v16.15.0
+v18.16.1
% npm -v
-v8.5.0
+v9.5.1
```
-+++
-
## Manual Installation (all platforms)
-You can download an appropriate installer package for your platform by visiting . *LTS* refers to the current *Long Term Support* version of `nodejs` and is the best choice for use with MyST.
+You can download an appropriate installer package for your platform by visiting . _LTS_ refers to the current _Long Term Support_ version of `nodejs` and is the best choice for use with MyST.
Download the installer package, and follow instructions to execute the installer for your platform. The installer will automatically add `node` and `npm` to your system PATH.
🛠️ Next, up [Installing MyST](./installing.md)
-+++
-
## `node` via `conda` / `mamba` (all platforms)
`nodejs` is available as a package on `conda-forge`, although a limited number of versions are available on that channel. If you are a `conda` user, installation is straightforward but please note that MyST requires even-numbered node versions, and odd-numbered releases can be found on `conda-forge`.
@@ -67,8 +60,6 @@ Download the installer package, and follow instructions to execute the installer
🛠️ Next, up [Installing MyST](./installing.md)
-+++
-
## `nodeenv` via pip (all platforms)
`nodeenv` is a python package allowing you to create and manage `node` installations on your system via virtual environments. If you want to work in virtual environments for `node` alongside your python `virtualenv` this is the way to go.
@@ -101,32 +92,28 @@ Read more about `nodeenv` in [their docs](https://ekalinin.github.io/nodeenv/).
🛠️ Next, up [Installing MyST](./installing.md)
-+++
-
## Node Version Manager - Linux/MacOS (`nvm`)
`nvm` is a convenient way to manage multiple node installations on a POSIX compatible system.
-🛠️ Install `nvm` using the install script:
+🛠️ Install `nvm` using the install script ([docs](https://github.com/nvm-sh/nvm#installing-and-updating)):
```shell
-% curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash
+% curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
% nvm -v
-0.39.1
+0.39.5
```
-💡 Note: on MacOS you can also install via `brew`
+💡 Note: on MacOS you can also install `nvm` via `brew`
🛠️ Next, install an initial (default) version of `node`\:
```python
-% nvm install 16
-Downloading and installing node v16.15.0...
+% nvm install 18
+Downloading and installing node v18.18.2...
...
-Now using node v16.15.0 (npm v8.5.5)
+Now using node v18.18.2 (npm v9.8.1)
%
```
Read more about `nvm` in [their docs](https://github.com/nvm-sh/nvm).
-
-🛠️ Next, up [Installing MyST](./installing.md)
diff --git a/docs/installing.md b/docs/installing.md
index 44eb6644b..8a9bf9c28 100644
--- a/docs/installing.md
+++ b/docs/installing.md
@@ -8,17 +8,18 @@ description: MyST Markdown is available through Node and npm, install the packag
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 mystmd
-```
+🛠️ [Install NodeJS](./installing-prerequisites.md), either version 16, 18 or 20
```{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).
+If you do not have `node` 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).
```
+🛠️ Choose either PyPI, Conda, Mamba or NPM and run the following command:
+
+:::{embed} #installing-myst-tabs
+:::
+
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:
```shell
diff --git a/docs/quickstart-myst-documents.md b/docs/quickstart-myst-documents.md
index 4a7cb2477..6b86c4a03 100644
--- a/docs/quickstart-myst-documents.md
+++ b/docs/quickstart-myst-documents.md
@@ -22,9 +22,8 @@ The tutorial will be brief on explaining MyST syntax, we provide a [MyST Markdow
```
````
-```{embed} install-myst-dropdown
-
-```
+:::{embed} install-myst-dropdown
+:::
:::{tip}
:class: dropdown
diff --git a/docs/quickstart-myst-websites.md b/docs/quickstart-myst-websites.md
index 401ceba65..62c351f17 100644
--- a/docs/quickstart-myst-websites.md
+++ b/docs/quickstart-myst-websites.md
@@ -21,11 +21,8 @@ The tutorial will be brief on explaining MyST syntax, we provide a [MyST Markdow
## 🛠 Install the MyST Markdown CLI
-🛠 Install the MyST command line tools, with `node` **greater than version v16**:
-
-```bash
-npm install -g mystmd
-```
+:::{embed} #installing-myst-tabs
+:::
:::{card} Need more help? See MyST Installation Quickstart
:link: ./quickstart.md
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 793455f13..58a7bec42 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -38,56 +38,104 @@ To follow along with this quickstart tutorial on your own computer, it is helpfu
`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
+:::{tip} Prerequisites - Install Node
:class: dropdown
You should have these programs installed:
-- [Node.js](https://nodejs.org) version **>=16.0.0**
+- [Node.js](https://nodejs.org) version **>=18.0.0**
- [Node Package Manager (npm)](https://docs.npmjs.com/about-npm) version **>=7.0.0**
- A code and notebook editor ([VSCode](https://code.visualstudio.com/) is great, and we recommend [Jupyter Lab](https://jupyter.org/install) for notebooks)
-If the node ecosystem is new to you[^conda], see our getting started guides for [installing node](./installing-prerequisites.md).
+If the node ecosystem is new to you, see our getting started guides for [installing node](./installing-prerequisites.md).
+:::
+
+🛠 Install the MyST command line tools:
+
+(installing-myst-tabs)=
+::::{tab-set}
+:::{tab-item} PyPI
+
+🛠 Install `node` (), see [Installing NodeJS](./installing-prerequisites.md):
+
+```bash
+node -v
+>> v20.4.0
+```
+
+🛠 Then install `mystmd`:
+
+```bash
+pip install mystmd
+```
+
+:::
+:::{tab-item} Conda / Mamba
+
+🛠 Install `node` (), or through conda (see [Installing NodeJS](./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/mystmd/issues/139) 🙏 🐍 🚀
+```bash
+# Visit https://nodejs.org or:
+conda install -c conda-forge 'nodejs>=20,<21'
+```
+
+Then install `mystmd`:
+
+```bash
+conda install mystmd -c conda-forge
+```
:::
+:::{tab-item} NPM
-Check your `node` installation **greater than version 16** (see [Installing NodeJS](./installing-prerequisites.md)):
+🛠 Install `node` (), see [Installing NodeJS](./installing-prerequisites.md)
```bash
node -v
->> v16.18.1
+>> v20.4.0
```
-🛠 Install the MyST command line tools:
+🛠 Install `mystmd` using npm, yarn or pnpm:
```bash
npm install -g mystmd
```
+:::
+::::
+
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). 🐛
-:::{danger} Note: `myst-cli` is deprecated
+:::::{note}
:class: dropdown
-In July 2023, we renamed the package to `mystmd` from `myst-cli`. Installing `myst-cli` will no longer create a `myst` command from your terminal. You can uninstall `myst-cli` using:
+**Updating MyST**
+
+There are new releases of the MyST Markdown CLI every few weeks, to update to the latest version of `myst`, use:
+
+::::{tab-set}
+:::{tab-item} PyPI
```bash
-npm uninstall -g myst-cli
+pip install -U mystmd
```
:::
+:::{tab-item} Conda / Mamba
-:::{note}
-:class: dropdown
-**Updating MyST**
+```bash
+conda update mystmd -c conda-forge
+```
-There are new releases of the MyST Markdown CLI every few weeks, to update to the latest version of `myst`, use:
+:::
+:::{tab-item} NPM
-```shell
+```bash
npm update -g mystmd
```
+:::
+::::
+
To get the latest templates, clean your templates directory with:
```shell
@@ -95,7 +143,8 @@ myst clean --templates
```
This will remove the `_build/templates` directory, which will be re-downloaded with the latest templates when you run `myst start` or `myst build`.
-:::
+
+:::::
## Download example content