From ed259846509b32ba1e4e77c99646d4ec02838256 Mon Sep 17 00:00:00 2001 From: Rowan Cockett Date: Thu, 9 Nov 2023 11:25:54 -0700 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=A6=20=F0=9F=93=96=20Installing=20myst?= =?UTF-8?q?md=20from=20conda,=20pypi,=20and=20npm=20(#732)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See #139 --- .github/workflows/ci.yml | 2 +- README.md | 20 +++++++- docs/installing-prerequisites.md | 47 +++++++----------- docs/installing.md | 13 ++--- docs/quickstart-myst-documents.md | 5 +- docs/quickstart-myst-websites.md | 7 +-- docs/quickstart.md | 81 +++++++++++++++++++++++++------ 7 files changed, 113 insertions(+), 62 deletions(-) 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