Create a website

🛠 Throughout the tutorial, whenever you’re supposed to do something you will see a 🛠

Build your first book¶

Next we’ll download some sample content and use jupyter book start to render it as a local web server!

Download example content¶

We provide an example project that includes a few simple markdown files and some Jupyter Notebooks. Through the course of the tutorials we will add content to these documents that show off some of the features of MyST.

🛠 Download the example content[^no-git], and navigate into the folder:

$ git clone https://github.com/jupyter-book/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/jupyter-book/mystmd-quickstart).

### Initialize Jupyter Book in the content folder 🚀

Next we will create a `myst.yml` configuration file that is required to render your project.
This is the [configuration file used by MyST](xref:guide/quickstart#initialize-myst-in-the-content-folder), and what Jupyter Book uses to control its behavior.

🛠 Run `jupyter book`

The `jupyter book` command is a shortcut for `jupyter book init`, which has a few more options for writing specific parts of the configuration file and a table of contents for your site.

```shell
$ jupyter book

Welcome to the Jupyter Book (via myst) CLI! 🎉 🚀

jupyter book init walks you through creating a myst.yml file.

You can use Jupyter Book (via myst) to:

 - create interactive websites from markdown and Jupyter Notebooks 📈
 - build & export professional PDFs and Word documents 📄

Learn more about this CLI and MyST Markdown at: https://jupyterbook.org


💾 Writing new project and site config file: myst.yml

Preview your book locally¶

Now that we a valid Jupyter Book project, we can preview it as a website to make sure that Jupyter Book is working properly.

🛠 When prompted, type Yes to install and serve your book locally:

? Would you like to run "jupyter book start" now? Yes

or manually serve the quickstart content with the following command:

$ jupyter book start

Starting the server requires a theme, this will download the default book-theme from the MyST themes. This can take up to a minute the first time, and then will be cached in the _build/templates directory.

🐕 Fetching template metadata from https://api.mystmd.org/templates/site/myst/book-theme
💾 Saved template to path _build/templates/site/myst/book-theme
⤵️ Installing web libraries (can take up to 60 s)
📦 Installed web libraries in 13 s
📖 Built interactive-graphs.ipynb in 21 ms.
📖 Built paper.md in 32 ms.
📖 Built README.md in 35 ms.
📚 Built 3 pages for myst in 82 ms.

  ✨✨✨  Starting Book Theme  ✨✨✨

⚡️ Compiled in 524ms.

🔌 Server started on port 3000!  🥳 🎉

  👉  http://localhost:3000  👈

🛠 Open your web browser to http://localhost:3000^[1]

The example site in this tutorial only has three pages and by default the 01-paper.md page is seen in Figure 1, which has minimal styles applied to the content.

🎉 Congratulations, you just build your first MyST site!

Configuration and structure¶

The final section of this tutorial takes a closer look at the files that we just created, and aspects of your book that can be customized.

Folder structure¶

If you are using a text editor, for example VSCode, open up the folder to explore the files:

quickstart/
  ├── 🆕 _build
  │   ├── exports
  │   ├── site
  │   │   ├── content
  │   │   ├── public
  │   │   └── config.json
  │   ├── temp
  │   └── templates
  │       ├── site/myst/book-theme
  │       └── tex/myst/arxiv_two_column
  ├── images
  │   ├── image.png
  │   └── image.gif
  ├── 01-paper.md
  ├── 02-notebook.ipynb
  ├── README.md
  └── 🆕 myst.yml

Running jupyter book init added:

• myst.yml - the configuration file for your myst project and site
• _build - the folder containing the processed content and other site assets, which are used by the local web server.

The _build folder also contains your templates (including the site template you installed) and any exports you make (when we build a PDF the exported document will show up in the _build/exports folder). You can clean up the built files at any time using myst clean^[2].

Configure site and page options¶

If we open and look inside our myst.yml we will see a basic configuration like this:

# See docs at: https://mystmd.org/guide/frontmatter
version: 1
project:
  # title:
  # description:
  keywords: []
  authors: []
  # github:
  # bibliography: []
site:
  template: book-theme
  # title:
  # options:
  #   logo: my_logo.png
  nav: []
  actions:
    - title: Learn More
      url: https://mystmd.org/guide
  domains: []

There are two important parts to the myst.yml:

project:

The project holds metadata about the collection of files, such as authors, affiliations and licenses for all of the files, any of these values can optionally be overridden in a file. To see all of the options see Frontmatter, which includes which fields can be overridden by files in the project.

site:

The site holds template information about the website, such as the logo, navigation, site actions and which template to use.

🛠 In myst.yml: Change the “# title:” comment in site to “title: Fancy Title 🎩” and save

Saving the myst.yml will have triggered a “full site rebuild”^[3]. Take a look at the browser tab and you’ll see that it has updated: