Setting up a local workspace

This page will explain how to install the Jupyter Book command-line tools on your device, and how to start a local development server using Visual Studio Code.

Install required tools¶

Before getting started, make sure the following are installed:

• An environment manager (pip will be used in this book)

• Git and/or Github Desktop

• Visual Studio Code (or another editor of choice)

If you prefer alternatives to pip, the Jupyter Book documentation describes several other installation methods

Install Jupyter Book¶

With the required tools in place, the next step is to install Jupyter Book itself.
This gives you access to the jupyter-book command-line tools. To install Jupyter Book, open a terminal and run:

pip install "jupyter-book>=2.0.0"

After installation, you can verify that Jupyter Book is available by checking the version:

jupyter book --version

which shows v2.0.0 if successfully installed.

Starting a project¶

There are 2 ways to start a project.

new project¶

The Jupyter Book package comes with an init command, used to initialise a new myst project in the current directory. Using VScode, open the project folder and start a terminal using ‘Ctrl + Shift + `’ (or by clicking Terminal > New Terminal). In the terminal, initialise a new jupyter book project:

jupyter book init

To get started writing content in your new project folder, refer to the Jupyter Book documentation.

Use template¶

Alternatively, there are several TUD templates to choose from.

[todo, link templates and how to use them]

Simple Browser extension¶

The Simple Browser extension provides an easy way to see live updates in VScode.

To open a live preview of your project, start a built-in server and open Simple Browser:

1. Start a local development instance

jupyter book start

Once loaded the project should be accessible through the local host, using a link similar to https://localhost:3000 (check the terminal).

2. Open Simple Browser from the command pallete. Press Ctrl+shirt+p and search for ‘simple browser’. When prompted for an URL, provide the URL shown in the command line.

Try saving an edit to a markdown file, and the change will be reflected on the webpage!

VSC¶

https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight