├── README.md └── images ├── screenshot-1.png ├── screenshot-2.png ├── screenshot-3.png ├── screenshot-4.png └── screenshot-5.png /README.md: -------------------------------------------------------------------------------- 1 | # How to create an on-line Jupyter Book from scratch 2 | 3 | I recently used the [jupyter-book](https://pypi.org/project/jupyter-book/) package to build an on-line book version of one of [my projects](https://github.com/pabloinsente/comp_models_cog_beh). This package simplifies the creation of websites hosting interactive [Jupyter Notebooks](https://jupyter.org/), by providing a series of scripts that will transform your Notebooks into Jekyll pages. [Jekyll](https://jekyllrb.com/) is a minimalistic static website and blog generator. Websites built with Jekyll can be freely and easily hosted with [GitHub pages](https://pages.github.com/). 4 | 5 | Instructions about how to build and deploy jupyter-book can be found in the [package documentation](https://jupyterbook.org/intro), which is an example of a jupyter-book in itself. Although the documentation is extensive and detailed, I had significant trouble building and deploying my notebooks in jupyter-book format. This is completely understandable, since jupyter-book is a project in active development, with lots of moving pieces, so sometimes the documentation may be unclear for some users (like me). 6 | 7 | My purpose is to provide a step-by-step guide to build a minimalistic version of jupyter-book. I'll explain everything as plain as possible, without very minimal assumptions about background knowledge. I only assume you know what the terminal is, and that you can type stuff in it to make things happen in your computer. I think jupyter-book is an amazing project, and that providing a guide to build and deploy a book may significantly help to increment its adoption, saving time and trouble to potential users. 8 | 9 | ## The situation 10 | 11 | You have a bunch of Jupyter Notebooks that you want to share with people. These may be the result of your analysis, a tutorial, workshop, or some other thing. Now, you have a couple of options: 12 | 13 | 1. **Run locally**: put everything on GitHub, and ask people to get the repo, set up their computers with all the requirements, and run everything locally. 14 | 2. **Run in binder**: put everything in GitHub, create a link to https://mybinder.org/ with the right configuration, so that people can run the notebooks in the cloud. 15 | 3. **Run on a website**: build a website with links to cloud computing instances. 16 | 17 | *Option 1* one is easier for you, but harder for the user. *Option 2*, is a bit harder for you, but easy for the user. *Option 3 is the hardest for you, but easier for the user*. Let's say you're willing to do more work to create the best possible experience for the user. This is when using jupyter-books is your best option. It minimizes the time and effort required to built the website and provides an outstanding experience to the user. 18 | 19 | ## What you need to begin 20 | 21 | At the minimum, you need these things: 22 | 23 | - A python 3.6 or 3.7 installation https://www.python.org/downloads/ 24 | - A git installation https://git-scm.com/book/en/v2/Getting-Started-Installing-Git 25 | - A UNIX-based system (Mac OS or any Linux distribution). If you are a Windows user, consider to use the [Linux Subsystem for Windows](https://docs.microsoft.com/en-us/windows/wsl/install-win10), [Gitbash](https://gitforwindows.org/), or [Cywin](https://www.cygwin.com/) 26 | - A couple of jupyter-notebooks (`.ipynb` extension) and/or markdown documents (`.md` extension) 27 | 28 | That's it. Technically, if you look at the [jupyter-book documentation](https://jupyterbook.org/guide/02_create.html), you'll see that there other things that would be nice to have beforehand, like a configuration file (i.e., `_config.yml`) and a table of contents file (i.e., `toc.yml`). However, those files are not strictly necessary to begin your project, so we will restrict ourselves to the bare minimum: *some content you want to put on-line*. 29 | 30 | ## Creating the book, step-by-step 31 | 32 | Now, we will create the book using the command line, step-by-step. 33 | 34 | ### Step 1: create directory for the book 35 | 36 | Open the terminal and navigate to your `Desktop` by: 37 | 38 | ```bash 39 | cd Desktop/ 40 | ``` 41 | 42 | Now, let's create a directory for the project 43 | 44 | ```bash 45 | mkdir my-book-files 46 | mkdir my-book-files/notebooks 47 | ``` 48 | 49 | ***Copy and paste your Jupyter Notebooks to the `my-book-files/notebooks/` folder*** 50 | 51 | ### Step 2: create and activate a virtual environment 52 | 53 | It is always a good idea to create a virtual environment to isolate your dependencies for each project. This is not strictly required, yet highly recommended. Make sure you are in the `Desktop` directory in your terminal and move to the project directory: 54 | 55 | ```bash 56 | # move to terminal to the project directory 57 | cd my-book-files/ 58 | ``` 59 | 60 | Once there, run this in the terminal to create the virtual environment: 61 | 62 | ```python 63 | # This line creates a virtual environment called 'venv' 64 | python3 -m venv venv 65 | # This line activates the virtual environment 66 | source venv/bin/activate 67 | ``` 68 | 69 | Once the virtual environment is activated, packages will be installed in that environment, without interfering with your python system installation. 70 | 71 | **HEADS UP**: if you close the terminal or deactivate `venv`, make sure to re-activate the virtual environment with `source venv/bin/activate` before typing any code. 72 | 73 | ### Step 3: install jupyter-book package 74 | 75 | The jupyter-book package can be pip-installed like this: 76 | 77 | ```python 78 | pip install jupyter-book 79 | ``` 80 | 81 | Now, if you run: 82 | 83 | ```bash 84 | pip list | grep jupyter-book 85 | ``` 86 | 87 | You should see something like this (version may change) printed to the terminal: 88 | 89 | ```bash 90 | jupyter-book 0.6.4 91 | ``` 92 | 93 | ### Step 4: create a jupyter-book template 94 | 95 | The whole point of `jupyter-book` is to provide a template that will make creating your book-site fast and easy. A template for your book can be created by running: 96 | 97 | ```bash 98 | jupyter-book create my-book 99 | ``` 100 | 101 | If correctly created, the (last part of the) output should look similar to this: 102 | 103 | ``` 104 | ================================================================================ 105 | 106 | Finished creating a new book at `./my-book` 107 | - Your content is in `./my-book/content` 108 | 109 | - A Table of Contents file is at `./my-book/_data/toc.yml`. 110 | You should check its contents, make sure it references your 111 | content correctly, and ensure it has the correct order. 112 | 113 | - Your configuration file is at `./my-book/_config.yml`. 114 | You should check its contents and double-check that the values are correct for your site. 115 | 116 | Notes 117 | ===== 118 | - Add your own content to your book. You haven't provided any content (`--content-folder`) 119 | so we've added a couple files to get you started. 120 | - We've added a CC-BY-SA license for you in ./my-book/content/LICENSE.md 121 | This is a reasonable license for most book content, though feel free 122 | to change it if you like! 123 | ================================================================================ 124 | ``` 125 | 126 | ### Step 5: remove the files in the `my-book/contents/` directory 127 | 128 | The `contents/` folder in the `my-book/` folder is the one containing the files and structure that will be used by the `jupyter-book` package to build your site. As of now, it contains a few demo files. Let's remove those files to then replace them with your content. 129 | 130 | Assuming that you are in `my-book-files/` directory, type this to remove the demo files: 131 | 132 | ```bash 133 | # remove .ipynb and .md files 134 | rm my-book/content/features/* 135 | # remove unnecesary images 136 | rm -r my-book/content/images/* 137 | # remove intro 138 | rm my-book/content/intro.md 139 | ``` 140 | 141 | Now, type this to look at the directory contents: 142 | 143 | ```bash 144 | # list directory with subdirectories 145 | ls -lR my-book/content/ 146 | ``` 147 | 148 | And the output should look similar to: 149 | 150 | ```bash 151 | my-book/content/: 152 | total 12 153 | drwxr-xr-x 2 pablo pablo 4096 Feb 10 17:09 features 154 | drwxr-xr-x 2 pablo pablo 4096 Feb 10 17:10 images 155 | -rwxr-xr-x 1 pablo pablo 257 Feb 10 16:19 LICENSE.md 156 | 157 | my-book/content/features: 158 | total 0 159 | 160 | my-book/content/images: 161 | total 0 162 | ``` 163 | 164 | This indicates that `my-book/content/` contains the `feature/` directory, an `images/` directory, and a `LICENSE.md` file. I keep the license file because it is a standard practice to have an open-source license for every project. If that doesn't work for you, just change the contents of the license as you need. 165 | 166 | ### Step 6: add your contents to the `my-book/contents/` directory 167 | 168 | Again, assuming you are in the `my-book-files/` directory in the terminal and that your content is in the `my-book-files/notebooks/`. Type this to incorporate your files into the book: 169 | 170 | ```bash 171 | cp -a notebook/* my-book/content/features/ 172 | ``` 173 | 174 | This will recursively copy the contents of your `notebook/` directory into the `my-book/content/features/` directory. 175 | 176 | **Note about images**: if you have images linked to your notebooks, this is what you need to do: 177 | 178 | - Make sure that the images are linked to your notebook by a *relative path* linked to the `images/` folder. The file structure should look like this: 179 | 180 | ```bash 181 | my-book-files/notebooks/notebook-with-the-linked-image.ipynb 182 | my-book-files/images/image-linked-to-notebook.png 183 | ``` 184 | 185 | - Now, if you have images, type this to pass the images into the book images folder: 186 | 187 | ```bash 188 | cp -a images/* my-book/content/images/ 189 | ``` 190 | 191 | - And you are done. 192 | 193 | **Note about an intro or about file**: 194 | 195 | - If you have some sort of introduction to your notebooks, let's say, an `intro.md` file, you just need to repeat the process of copying the file to the `my-book/content/` directory: 196 | 197 | ``` 198 | cp intro.md my-book/content/ 199 | ``` 200 | 201 | Assuming that you have a `notebooks/` directory, an`images/` directory, and an `about.md` file, your `my-book/content/` directory should look like this now: 202 | 203 | ```bash 204 | # list directory with subdirectories 205 | ls -lR my-book/content/ 206 | # output printed to the terminal 207 | my-book/content/: 208 | total 12 209 | -rw-r--r-- 1 pablo pablo 0 Feb 10 17:37 intro.md 210 | drwxr-xr-x 2 pablo pablo 4096 Feb 10 17:24 features 211 | drwxr-xr-x 2 pablo pablo 4096 Feb 10 17:37 images 212 | -rwxr-xr-x 1 pablo pablo 257 Feb 10 16:19 LICENSE.md 213 | 214 | my-book/content/features: 215 | total 124 216 | -rw-r--r-- 1 pablo pablo 34958 Feb 7 10:24 01-notebook.ipynb 217 | -rw-r--r-- 1 pablo pablo 10221 Feb 7 10:54 02-notebook.ipynb 218 | -rw-r--r-- 1 pablo pablo 74105 Feb 7 10:24 03-notebook.ipynb 219 | 220 | my-book/content/images: 221 | total 0 222 | -rw-r--r-- 1 pablo pablo 0 Feb 10 17:37 image1.png 223 | -rw-r--r-- 1 pablo pablo 0 Feb 10 17:37 image2.png 224 | ``` 225 | 226 | ### Step 7: create a table of contents file matching the contents of your book 227 | 228 | Now that you have your contents in place, you need a *table of contents* to match that. The table of contents is the `my-book/_data` in the `toc.yml` file. You have two options for this: to modify the existing `toc.yml` file to match the contents or to create a new one from scratch. The existing one has too much info to absorb, so I'll create a new one to explain each component. Feel free to use your favorite text editor to edit the file. 229 | 230 | ```bash 231 | # create an empty toc.yml file 232 | touch toc.yml 233 | # open the file in nano / or use whatever you like 234 | nano toc.yml 235 | ``` 236 | 237 | From the jupyter-book documentation, we know that each `toc.yml` has the following schema: 238 | 239 | ```bash 240 | # - title: mytitle # Title of chapter or section 241 | # url: /myurl # URL of section relative to the /content/ folder. 242 | # sections: # Contains a list of more entries that make up the chapter's sections 243 | # not_numbered: true # if the section shouldn't have a number in the sidebar 244 | # (e.g. Introduction or appendices) 245 | # expand_sections: true # if you'd like the sections of this chapter to always 246 | # be expanded in the sidebar. 247 | # external: true # Whether the URL is an external link or points to content in the book 248 | # 249 | # Below are some special values that trigger specific behavior: 250 | # - search: true # Will provide a link to a search page 251 | # - divider: true # Will insert a divider in the sidebar 252 | # - header: My Header # Will insert a header with no link in the sidebar 253 | ``` 254 | 255 | Next, let's populate the file with a few elements. Remember that the path to the files are relative to the `contents/` directory. 256 | 257 | **HEADS UP**: 258 | 259 | - each `.md` and `.ipynb` file has to have some content in it. Also remember to add a top header (with # My title), since it will be used as the title to the section on the website. 260 | - Remember to *omit* the file extension ( `.md` and `.ipynb` ) when passing the URL 261 | 262 | ```bash 263 | # add the top header 264 | - header: My Jupyter Book 265 | 266 | # add the 'about.md' section at the top 267 | - url: /intro 268 | not_numbered: true 269 | 270 | # add a divider: a divider is just a black line separating sections. It is just aesthetics. 271 | - divider: true 272 | 273 | # add a second header 274 | - header: Contents 275 | 276 | # add the first notebook 277 | - url: /features/01-notebook 278 | not_numbered: true 279 | 280 | # add the second notebook 281 | - url: /features/02-notebook 282 | not_numbered: true 283 | 284 | # add the third notebook 285 | - url: /features/03-notebook 286 | not_numbered: true 287 | 288 | # another divider 289 | - divider: true 290 | 291 | # add the LICENSE 292 | - url: /LICENSE 293 | not_numbered: true 294 | ``` 295 | 296 | Now, let's remove the old `toc.yml` file and paste the new one: 297 | 298 | ```bash 299 | rm my-book/_data/toc.yml 300 | cp toc.yml my-book/_data/ 301 | ``` 302 | 303 | ### Step 8: add a `requirements.txt` file 304 | 305 | The chances are that you are using some python package for your analysis. If so, you'll need to create a `requirements.txt` file containing the package names and versions for your project: 306 | 307 | ```bash 308 | # create an empty toc.yml file 309 | touch requirements.txt 310 | # open the file in nano 311 | nano requirements.txt 312 | ``` 313 | 314 | Then, populate your `requirements.txt` with your dependencies. For instance, in my case they look like this: 315 | 316 | ```bash 317 | altair==4.0.1 318 | numpy==1.18.1 319 | matplotlib==3.1.2 320 | pandas==0.25.2 321 | jupyterlab==1.2.5 322 | keras==2.3.1 323 | vega_datasets 324 | ``` 325 | 326 | Note that if you just want the latest version of the package to be used, you can omit the `==version-number` part (as in the `vega_datasets`), and just pass the package name. This is not recommended because future releases of the package may break your code functionality. The best is just to figure out the exact package versions you are using. One way is to type `pip list` (assuming you are using `pip`) or `conda list` (if you are using `conda`) in the terminal, in the directory and environment where you ran your code. 327 | 328 | Now, let's remove the old `requirements.txt` file and paste the new one: 329 | 330 | ```bash 331 | rm my-book/requirements.txt 332 | cp requirements.txt my-book/ 333 | ``` 334 | 335 | ### Step 9: create a GitHub account and a repository for the project 336 | 337 | If you have a GitHub account already, you may be tempted to use your existing account to deploy your project. This may not be a good idea because that may interfere with your ability to use your GitHub account to deploy something more personal in the future, like a resume page or a blog. Also, if you are using GitHub pages already, deploying the site without messing up with your existing website may be tricky. Therefore, it is highly recommended to *create a GitHub account for the project*. You'll need an email account *not associated* with an existing GitHub account. With that, you can go to https://github.com/ and follow the Sign Up instructions. 338 | 339 | 340 | 341 | Once you are ready with your new account, create a new *empty repository* for the project. That is, no *README*, no *LICENSE*, no *.gitignore*. Just empty. Normally, GitHub should prompt you to create a new repo when you verify your email account. If you created one, you can use that one for the next steps. Otherwise, follow steps 1 through 6 in the instructions here https://help.github.com/en/github/getting-started-with-github/create-a-repo 342 | 343 | 344 | 345 | You can name your repo as you like, but let's assume that you name it `my-book-site/`. Now we need to connect the online repo with your machine. This time, make sure you are in your local `my-book/` directory, and follow these instructions: 346 | 347 | ```bash 348 | # navigate to the book directory 349 | cd my-book 350 | # initialize tracking 351 | git init 352 | ``` 353 | 354 | The terminal should print back a message like this 355 | 356 | ```bash 357 | Initialized empty Git repository in /home/YOUR-USERNAME/Desktop/my-book-files/my-book/.git/ 358 | ``` 359 | 360 | Next, stage the files to be committed 361 | 362 | ```bash 363 | # stage the files to be commited 364 | git add -A 365 | ``` 366 | 367 | Now you need to commit the files that will be pushed to GitHub. Depending on your git configuration, the terminal may prompt you to enter your `user.email` and `user.name`. Use your newly created GitHub email and username for this, omitting the `--global` option (if you set up this globally, it may generate problems for you later on). 368 | 369 | ```bash 370 | # commit the files to be pushed 371 | git commit -m "First commit" 372 | 373 | # assuming it asks you "*** Please tell me who you are" 374 | git config user.email "your.ney.email@gmail.com" 375 | git config user.name "your-new-github-username" 376 | # repeat the commit if necessary 377 | git commit -m "First commit" 378 | ``` 379 | 380 | Next, connect your new GitHub repo with your local directory. You can get the URL of your repo in the repo home-page bellow "*Quick setup — if you’ve done this kind of thing before*" 381 | 382 | ```bash 383 | # here, replace with your real username 384 | # also replace with the name you gave to your repo 385 | git remote add origin https://github.com/your-github-username/my-book-site.git 386 | ``` 387 | 388 | Finally, you need to push your local files to the GitHub repo. Notice that git should prompt you to enter your username and password. Use your newly created ones for the project: 389 | 390 | ```bash 391 | # push the files 392 | git push origin master 393 | 394 | # If git prompts you: 395 | Username for 'https://github.com': your-github-username 396 | Password for 'https://my-first-jupyter-book@github.com': your-password 397 | ``` 398 | 399 | ### Step 10: create a `_config.yml` configuration file 400 | 401 | The last file we need to add is the `_config.yml` file. Again, one option is just to edit the existing `_config.yml` file in the `my-book/` directory. I'll fill in this step-by-step, again, just for the sake of explaining in detail what are you doing here: 402 | 403 | ```bash 404 | # if you were at the my-book/ directory, go back to the my-book-files/ directory 405 | cd .. 406 | # create a new _config.yml file 407 | touch _config.yml 408 | # open it in your favorite edito, I'll use nano 409 | nano _config.yml 410 | ``` 411 | 412 | This may look long and complicated, but it is not. You just need to **copy-paste everything to your `_config.yml`** and change a couple of lines that I'll flag for you with capitals as `#@@@ CHANGE THIS - number @@@#`. To make sure you don't miss any, I numbered the changes from 1 to 9. 413 | 414 | ```bash 415 | ###################### 416 | # Jekyll site settings 417 | ###################### 418 | title: my-first-jupyter-book #@@@ CHANGE THIS -1 @@@# 419 | author: Pablo Caceres #@@@ CHANGE THIS -2 @@@# 420 | email: my.first.jupyter.book@gmail.com #@@@ CHANGE THIS -3 @@@# 421 | description: >- # this means to ignore newlines until "baseurl:" 422 | My brand new book #@@@ CHANGE THIS - 4 @@@# 423 | 424 | # the name of your GitHub Repo. 425 | # If there is no subpath for your site, use an empty string "" 426 | baseurl: "/my-book-site" #@@@ CHANGE THIS -5 @@@# 427 | 428 | 429 | # the base hostname & protocol for your site. 430 | # Since we are deloying on GitHub pages, the URL has the format: 431 | # "https://your-github-username.github.io/" 432 | # In my case is: 433 | url: "https://my-first-jupyter-book.github.io/" #@@@ CHANGE THIS - 6 @@@# 434 | 435 | ####################### 436 | # Jupyter Book settings 437 | ####################### 438 | 439 | # Main page settings 440 | # Optional: you can replace with your repo URL 441 | footer_text : View source repository at #@@@ CHANGE THIS - 7 @@@# 442 | 443 | # Sidebar settings 444 | show_sidebar : true # Show the sidebar. Only set to false if your only wish to host a single page. 445 | collapse_inactive_chapters: true # Whether to collapse the inactive chapters in the sidebar 446 | collapse_inactive_sections: true # Whether to collapse the sub-sections within a non-active section in the sidebar 447 | #textbook_logo : images/logo/logo.png # A logo to be displayed at the top of your textbook sidebar. Should be square 448 | #textbook_logo_link : https://jupyterbook.org/intro.html # A link for the logo. 449 | sidebar_footer_text : 'Powered by Jupyter Book' 450 | number_toc_chapters : true # Whether to add numbers to chapterse in your Table of Contents. If true, you can control this at the Chapter level in _data/toc.yml 451 | 452 | # Search settings 453 | search_max_words_in_content : 100 # In the search function, use at most this many words (too many words will make search slow) 454 | 455 | # Controlling page information 456 | page_titles : infer # Either `None`, `infer`, or `toc` 457 | page_authors : None # Either `None` or `infer` 458 | filename_title_split_character : '_' # If inferring titles based on filename, splt on this character. 459 | 460 | # Math settings 461 | number_equations : false # Whether to automatically number all block equations with MathJax 462 | 463 | ######################## 464 | # Interact link settings 465 | ######################## 466 | 467 | # General interact settings 468 | use_jupyterlab : false # If 'true', interact links will use JupyterLab as the interface 469 | 470 | # Jupyterhub link settings 471 | use_jupyterhub_button : false # If 'true', display a button that will direct users to a JupyterHub (that you provide) 472 | jupyterhub_url : "" # The URL for your JupyterHub. If no URL, use "" 473 | jupyterhub_interact_text : "Interact" # The text that interact buttons will contain. 474 | 475 | # Binder link settings 476 | use_binder_button : true # If 'true', add a binder button for interactive links 477 | binderhub_url : https://mybinder.org # The URL for your BinderHub. If no URL, use "" 478 | 479 | 480 | binder_repo_base : https://github.com/my-first-jupyter-book/my-book-site #@@@ CHANGE THIS @@@ -8 # # The site on which the textbook repository is hosted 481 | binder_repo_org : my-first-jupyter-book #@@@ CHANGE THIS @@@ - 9# # Your GitHub username 482 | 483 | binder_repo_name : my-book-site # The project repo name 484 | binder_repo_branch : master # The branch on which your textbook is hosted. 485 | binderhub_interact_text : "Interact via Binder" # The text that interact buttons will contain. 486 | 487 | # Thebelab settings 488 | use_thebelab_button : true # If 'true', display a button to allow in-page running code cells with Thebelab 489 | thebelab_button_text : "Thebelab" # The text to display inside the Thebelab initialization button 490 | codemirror_theme : "abcdef" # Theme for codemirror cells, for options see https://codemirror.net/doc/manual.html#config 491 | 492 | # nbinteract settings 493 | use_show_widgets_button : true # If 'true', display a button to allow in-page running code cells with nbinteract 494 | 495 | # Download settings 496 | use_download_button : true # If 'true', display a button to download a zip file for the notebook 497 | download_button_text : "Download" # The text that download buttons will contain 498 | download_page_header : "Made with Jupyter Book" # A header that will be displayed at the top of and PDF-printed page 499 | 500 | ####################################################################################### 501 | # Jupyter book settings you probably don't need to change 502 | 503 | content_folder_name : "content" # The folder where your raw content (notebooks/markdown files) are located 504 | images_url : "/assets/images" # Path to static image files 505 | css_url : "/assets/css" # Path to static CSS files 506 | js_url : "/assets/js" # Path to JS files 507 | custom_static_url : "/assets/custom" # Path to user's custom CSS/JS files 508 | 509 | ####################################################################################### 510 | # Jekyll build settings (only modify if you know what you're doing) 511 | 512 | # Site settings 513 | defaults: 514 | - scope: 515 | path: "" 516 | values: 517 | layout: "default" 518 | toc: true 519 | toc_label: " On this page" 520 | toc_icon: "list-ul" 521 | excerpt: '' 522 | 523 | favicon_path: "images/logo/favicon.ico" 524 | 525 | # Markdown Processing 526 | markdown: kramdown 527 | kramdown: 528 | input: GFM 529 | syntax_highlighter: rouge 530 | 531 | sass: 532 | style: compressed 533 | 534 | collections: 535 | build: 536 | output: true 537 | permalink: /:path.html 538 | 539 | # Exclude from processing. 540 | # The following items will not be processed, by default. Create a custom list 541 | # to override the default setting. 542 | exclude: 543 | - scripts/ 544 | - Gemfile 545 | - Gemfile.lock 546 | - node_modules 547 | - vendor/bundle/ 548 | - vendor/cache/ 549 | - vendor/gems/ 550 | - vendor/ruby/ 551 | 552 | plugins: 553 | - jekyll-redirect-from 554 | - jekyll-scholar 555 | 556 | # Jupyter Book version - DO NOT CHANGE THIS. It is generated when a new book is created 557 | jupyter_book_version: "0.6.4" 558 | ``` 559 | 560 | Once you are done with the 9 changes, replace the old `_config.yml` with the new one: 561 | 562 | ```bash 563 | rm my-book/_config.yml 564 | cp _config.yml my-book/ 565 | ``` 566 | 567 | ### Step 11: build the `html` files to deploy with `jupyter-book` 568 | 569 | Everything is in place now. The last step before deploying your site is to build the `html` files like this: 570 | 571 | ```bash 572 | jupyter-book build my-book/ 573 | ``` 574 | 575 | If successful, the terminal should print something like: 576 | 577 | ```bash 578 | ================================================================================ 579 | 580 | 581 | Generated 5 new files 582 | Skipped 0 already-built files 583 | Your Jupyter Book is now in `_build/`. 584 | Demo your Jupyter book with `make serve` or push to GitHub! 585 | 586 | 587 | ================================================================================ 588 | ``` 589 | 590 | ### Step 12: push the site contents to GitHub and deploy as GitHub pages 591 | 592 | You can test your site locally by navigating into your book and running `make serve`. You need Ruby and a bunch of tools (gems) installed to do that, so I won't get into that now. Let's push and deploy on GitHub pages. 593 | 594 | First, add, commit, and push the changes to GitHub: 595 | 596 | ```bash 597 | git add -A 598 | git commit -m "my first jupyter book" 599 | git push origin master 600 | ``` 601 | 602 | Now, go to the repo`Setting` as shown in the picture below 603 | 604 | ![](images/screenshot-1.png) 605 | 606 | Then, enable `GitHub pages` in your master branch as shown below 607 | 608 | ![](images/screenshot-2.png) 609 | 610 | If successful, you should see this message: 611 | 612 | ![](images/screenshot-3.png) 613 | 614 | After a couple of minutes (usually 1 or 2 minutes), you should see this message (refresh the page too see the update): 615 | 616 | ![](images/screenshot-4.png) 617 | 618 | Finally if you click the link, and everything went well, your site should be ready to use! for instance, the page that I created for this tutorial can be found [here](https://my-first-jupyter-book.github.io/my-book-site/intro.html), and it looks like this: 619 | 620 | ![](images/screenshot-5.png) 621 | 622 | ### Bonus: updating your site 623 | 624 | You may need to update your site from time to time. There are two situations: when you modify files maintaining the same structure, and when you add new elements, like another markdown file or Jupyter Notebook. 625 | 626 | In the first scenario, you need to: 627 | 628 | 1. add the changes to the website local repo 629 | 2. rebuild the site running `jupyter-book build my-book/` again 630 | 3. push the changes to GitHub. 631 | 632 | The site should be rebuilt online by GitHub pages with the changes 633 | 634 | In the second scenario, you need to: 635 | 636 | 1. add the new files to the website local repo 637 | 2. modify the `toc.yml` to match your new file structure (`url`) 638 | 3. rebuild the site running `jupyter-book build my-book/` again 639 | 4. push the changes to GitHub. 640 | 641 | 642 | 643 | That's it. I hope this tutorial was helpful. For more details and info please check the [oficial jupyter-book documentation](https://jupyterbook.org/intro). 644 | 645 | *** 646 | 647 | This is my professional website: https://pablocaceres.org/ 648 | 649 | This is my Twitter account: https://twitter.com/CodeBug88 650 | 651 | This is my GitHub account: https://github.com/pabloinsente 652 | 653 | [Back to the top](#how-to-create-an-on-line-jupyter-book-from-scratch) 654 | 655 | -------------------------------------------------------------------------------- /images/screenshot-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pabloinsente/jupyter-book-tutorial/8a643faa21cd847d704af0655d810b46c17b03a1/images/screenshot-1.png -------------------------------------------------------------------------------- /images/screenshot-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pabloinsente/jupyter-book-tutorial/8a643faa21cd847d704af0655d810b46c17b03a1/images/screenshot-2.png -------------------------------------------------------------------------------- /images/screenshot-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pabloinsente/jupyter-book-tutorial/8a643faa21cd847d704af0655d810b46c17b03a1/images/screenshot-3.png -------------------------------------------------------------------------------- /images/screenshot-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pabloinsente/jupyter-book-tutorial/8a643faa21cd847d704af0655d810b46c17b03a1/images/screenshot-4.png -------------------------------------------------------------------------------- /images/screenshot-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pabloinsente/jupyter-book-tutorial/8a643faa21cd847d704af0655d810b46c17b03a1/images/screenshot-5.png --------------------------------------------------------------------------------