jupyter-book · fwkoch · Nov 9, 2023 · Nov 7, 2023 · fwkoch · Nov 7, 2023
diff --git 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
@@ -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 (<https://nodejs.org/>):
 
 ```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
@@ -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 <https://nodejs.org/>. *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 <https://nodejs.org/>. _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
@@ -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
@@ -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
@@ -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
@@ -38,64 +38,113 @@ 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` (<https://nodejs.org>), 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` (<https://nodejs.org>), 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` (<https://nodejs.org>), 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
 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