chore: restructure

executablebooks · Jul 8, 2024 · 8c4b41f · 8c4b41f
1 parent e76e6fe
commit 8c4b41f
Show file tree

Hide file tree

Showing 9 changed files with 65 additions and 25 deletions.
diff --git a/about/why-switch-mystmd.md b/about/why-switch-mystmd.md
@@ -0,0 +1,42 @@
+---
+title: History of the Jupyter Book Project
+subtitle: A brief history of the Jupyter Book project, and the journey it took along the way.
+# subject: MyST Quickstart Tutorial
+short_title: History of Jupyter Book
+---
+
+:::{mermaid}
+gantt
+    dateFormat  YYYY-MM
+    title       The history of Jupyter Book
+
+    Jupyter Book 0.1 - 0.7 (Jekyll)               :active,  des2, 2018-06, 2020-07
+    Jupyter Book 0.7 - 1.x (Sphinx)               :active,  des2, 2020-07, 2024-07
+    Jupyter Book 1.0 : milestone, 2020-02, 1d
+    Jupyter Book 2.x (MyST-MD)               :active,  des2, 2024-07, 2024-07
+
+:::
+
+## A History of Jupyter Book
+### Jupyter Book 0.1-0.7
+
+The Jupyter Book project was started in June of 2018, with [Chris Holdgraf](https://chrisholdgraf.com/) writing [the first commit](https://github.com/executablebooks/jupyter-book/commit/4fc6636c652cebea71556f634c9a37e0740ab26f). Initially, work was focussed on building a series of scripts to compile Jupyter Notebooks into a textbook using [Jekyll](https://jekyllrb.com/).
+
+### Jupyter Book 0.7-1.0
+In 2020, the "new" Jupyter Book (0.7) [was announced](https://executablebooks.org/en/latest/blog/2020-08-07-announce-book/) which re-built Jupyter Book from the ground up to make it 
+> easier to install, faster to use, and able to create more complex publishing content in your books.
+>
+> -- Executable Books
+
+This work was supported by the Executable Books project, an open community building open-source tools [powered by a grant from the Sloan foundation](https://executablebooks.org/en/latest/blog/2020-02-25-hello-world/#hello-world).
+
+The 0.7 re-write established the Jupyter Book application on top the Sphinx documentation engine, which was at the time used primarily for documentation of Python projects. With this move to Sphinx, a new Markdown dialect _MyST Markdown_ (Markedly Structured Text Markdown) was created to combine the expressiveness of Sphinx's Restructured Text with the familiarity and readability of Markdown. 
+
+In addition to using a new documentation engine, Jupyter Book 0.7 saw the introduction of Thebe which brought interactivity and widgets to published books using the power of [Binder](https://mybinder.org).
+
+
+### Jupyter Book 1.0-1.x
+In 2023, a broad effort to recognize the stability of the Jupyter Book software stack was made through a series of 1.0 releases. This saw updates to core Jupyter Book packages such as `myst-nb` and `sphinx-book-theme` to support Sphinx 7 and Python 3.11+, and marked the "maintenance phase" of the Jupyter Book tools.
+
+### Jupyter Book 2
+As outlined above, Jupyter Book has a long history. Over its lifetime, it has become a well-established tool for authoring and publishing in the Jupyter ecosystem with [over 13,000 GitHub repositories now using the tool](https://executablebooks.org/en/latest/blog/2024-05-20-jupyter-book-myst/). During that time, the Executable Books team have learned a great deal about the ways in which our communities use Jupyter Book, witnessed first-hand the pain-points in building a book publishing tool on top of Sphinx, and [explored new ways in which the Jupyter Book tools can be used](https://executablebooks.org/en/latest/blog/2023-02-09-announce-mystjs/#myst-is-now-a-top-level-project-in-executable-books). Following these learnings, and the sucess of the MyST-MD project that was launched in 2022, it became clear that the future of Jupyter Book lay in a new direction.
diff --git a/reference/glossary.md → glossary.md b/reference/glossary.md → glossary.md
diff --git a/install.md b/install.md
@@ -49,7 +49,6 @@ Installing software can be confusing. Here's a simple guide to making a sensible
 
 :::{card} 
 :header: Install with `pip` 🐍
-:name: card:install-pip
 
 In a [virtual environment][venv]:
 ```shell
@@ -59,7 +58,6 @@ pip install jupyter-book>=2
 
 :::{card} 
 :header: Install with [`mamba`][mamba] / `conda` 🔥
-:name: card:install-mamba
 
 ```shell
 mamba install -c conda-forge \
@@ -69,7 +67,6 @@ mamba install -c conda-forge \
 
 :::{card} 
 :header: Install with [`pipx`][pipx] ⚙️
-:name: card:install-pipx
 
 Never heard of `pipx`? See [the documentation][pipx] for more.
 
@@ -80,7 +77,6 @@ pipx install jupyter-book>=2
 
 :::{card} 
 :header: Install with [`pixi`][pixi] 🔥
-:name: card:install-pixi
 
 Never heard of `pixi`? See [the documentation][pixi] for more.
 

diff --git a/myst.yml b/myst.yml
@@ -16,15 +16,15 @@ project:
     - file: upgrade.md
     - title: Create a Book
       children: 
-        - file: start/create.md
+        - file: start/init.md
         - file: start/build.md
         - file: start/new-file.md
         - file: start/cross-reference.md
         - file: start/publish.md
-    - title: Reference
+    - title: About Jupyter Book
       children: 
-        - file: reference/glossary.md
-        - file: reference/why-switch-mystmd.md
+        - file: about/why-switch-mystmd.md
+    - file: glossary.md
 site:
   template: book-theme
   options:

diff --git a/overview.md b/overview.md
@@ -1,6 +1,6 @@
 ---
 title: Welcome to Jupyter Book
-subtitle: Build beautiful, publication-quality books and documents from computational content.
+subtitle: Build beautiful, publication-quality books and documents from computational content using MyST-MD.
 ---
 
 ::::{grid} 1 2 2 2

diff --git a/reference/why-switch-mystmd.md b/reference/why-switch-mystmd.md
diff --git a/start/create.md b/start/create.md
diff --git a/start/init.md b/start/init.md
@@ -0,0 +1,16 @@
+---
+title: Initialise a Project
+subtitle: Use the Jupyter Book CLI to quickly get started.
+subject: Jupyter Book Quickstart Tutorial
+---
+
+:::{important} Objective
+The goal of this tutorial is to use the `jupyter book init` command to start a simple website.  
+:::
+
+## Running `jupyter book init`
+
+Jupyter Book ships with an `init` command, which initializes a `myst` project in the current directory.
+```shell
+$ jupyter book init
+```
diff --git a/upgrade.md b/upgrade.md
@@ -2,7 +2,7 @@
 title: Upgrade an Existing Book From Jupyter Book 1
 subtitle: Use automated tools to upgrade a legacy (Sphinx-based) Jupyter Book project to the new MyST engine.
 # subject: MyST Quickstart Tutorial
-short_title: Upgrade a Book ⭐
+short_title: Upgrade an Old Book ⭐
 ---
 
 :::{important} Objective
@@ -199,7 +199,7 @@ Neither Jupyter Book 1 and 2 do anything useful with a `requirements.txt` file,
 
 ## Upgrading a {term}`Legacy Book`
 
-Whilst Jupyter Book 1 was built upon the _Sphinx_ document engine, Jupyter Book 2 is built upon the [_MyST-MD_ engine](https://mystmd.org). The reasons for this transition are outlined in [](./reference/why-switch-mystmd.md). Unlike Jupyter Book 1, Jupyter Book 2 does not try to hide the fact that it is built on a different engine; MyST-MD is designed from the ground up to be good at technical writing, and the Executable Books team believe that it is both powerful and easy-to-use. As such, Jupyter Book 2 builds on top of MyST-MD, using the same CLI and `myst.yml`. 
+Whilst Jupyter Book 1 was built upon the _Sphinx_ document engine, Jupyter Book 2 is built upon the [_MyST-MD_ engine](https://mystmd.org). The reasons for this transition are outlined in [](./about/why-switch-mystmd.md). Unlike Jupyter Book 1, Jupyter Book 2 does not try to hide the fact that it is built on a different engine; MyST-MD is designed from the ground up to be good at technical writing, and the Executable Books team believe that it is both powerful and easy-to-use. As such, Jupyter Book 2 builds on top of MyST-MD, using the same CLI and `myst.yml`. 
 
 ::: {pull-quote}
 Unlike Jupyter Book 1, Jupyter Book 2 does not try to hide the underlying engine.