@emdupre mentioned that the current guide isn't super clear about how people can modify the jupyter book content - this should be improved, maybe with a nicer set of sub-sections and some examples for particular looks (in particular, the distill.pub style is really nice)

I'm not sure this is a problem (not even sure it's a problem, or the problem is my poor HTML chops...) of jupyter-book but I've ran into it and might be or relevance for other folks. I'm automatically converting .md files from GitHub repos that include badges from Travis, etc. When I render the book, they look too big. See, next to the md file resulting from building the book:

Is there any obvious easy solution? Ideally, I'd like to keep the badges too as they're useful information for the book audience.

Thank you very much, and thank you very much for (another) awesome project!

]d[

I've got a feature request: is it possible to add to _config.yml an option to embed a link to sidebar logo? There is currently a logo on the side bar without any embedded link. For my case I'd like to point it to the github repository. Does it sound reasonable?

I quite liked the search bar on the old version of the website - I think that seems to have gone in the new one? Is there an easy way to add it back in, through config, to have the search bar?

This is an issue to discuss some kind of "single document mode" in Jupyter Book.

The general goal

Make it possible to convert a single ipynb file into a standalone HTML file like so:

jupyter-book report path/to/myfile.ipynb

The output should be:

1. A single HTML file
2. Have all images and linked CSS/JS included with it
3. Have customizable binder/jupyterhub/thebelab buttons

Why this would be useful

It's common for people to want to generate a "report" from a Jupyter notebook. These are often a bit clunky, since you can't double-click them and they need a jupyter server to work properly. Making it possible to easily create some beautiful HTML document with moderate interactivity would be helpful.

Some challenges

• Currently, our conversion to markdown creates a new image file for each output image. If we need a single output file, we'd need to embed them in the markdown / HTML.
  • I think doing the conversion with pandoc would let us do this relatively easily with standalone mode
• Currently we are linking CSS/JS from the head of each HTML page, but a standalone document would need those included in it, not linked

cc @emdupre and @betatim who were chatting about this on the twitterz :-)

Thanks for your works.

I'd like to insert disqus comments box on the jupyter-book webpage.

A guide said, I should add disqus_url & disqus_id lines in the _config.yaml file

And generate disqus_comments.html file on _includes foler.

However, it does not works.

Do you how to solve this problem?

Thanks.

I have about 8~10 issues with MathJax reading certain parts of a notebook incorrectly. Does this require a case by case fix? They are showing up as intended in the ipython notebooks.

Examples: 14.1 see technical note, 14.4 midway down the page.
See original notebooks here

Is there a basic methodology for trouble shooting? I'm not well rehearsed in MathJax syntax.

Currently, thebelab always runs in the home directory. It would be really convenient, if it were started in the subdirectory of the current page, e.g. contents/chapter_X. This way I could add chapter-dependent code files in this subdirectory. This would also fit with the current behavior of the "interact" button.

I wonder if this would be possible by modifying this line using the current page's data?

https://github.com/jupyter/jupyter-book/blob/493b346d888ee7c863d93c73abb53f038a54a89c/jupyter_book/book_template/_includes/js/thebelab.html#L8

I was chatting with @emdupre and she mentioned it'd be cool if Jupyter Book allowed for more "publishing-style" content where you could cite work. I don't know that Markdown supports this natively, but there may be some jekyll plugins etc that could make this possible.

One example I found is this: https://github.com/inukshuk/jekyll-scholar but we should keep this issue to track anything new as we learn about it.

In a fair amount of academic writing, it is helpful to have numbered equations and figures so that they can be referenced in the text of the document. Is it possible to have "labeled" equations and figures so that they can be referenced and hyperlinked throughout Jupyterbook? On a related note, can captions be added to figures?

Is there still a way to autogenerate the toc file, that now lives in data/toc.yml?

The old script to do this was quite useful, especially when deploying a site that updates periodically. Is there anything that prevents doing this with the new organization? Given a couple assumptions about what ends up in content/ is seems this should be automatable (with more complicated builds / organizations perhaps requiring manual editing).

I'm currently developing a Jupter book using this wonderful project. However I'm running into one issue with table rendering in Jupyter R notebook.

Problem

The table header are messed up in the HTML output:

Reproducing it

To save you the efforts reproducing the issue please find attached the relevant section from the intermediate markdown file exported by the build script into the _build folder:

R_dataframe_output.md.txt

The <div markdown="0" class="output output_html"> in question was automatically generated from Jupyter notebook.

Software versions

> jupyter-notebook --version
5.6.0

2. jupyter-book version: the current master.

Please let me know if you need more information. Looking forward to hearing from you!

I got this error but I cannot figure how to fix it ( some similar errors about from notebook import DEFAULT_STATIC_FILES_PATH can be found on web):

C:\Python364>jupyter-book create mybookname --demo
Traceback (most recent call last):
  File "c:\python364\lib\runpy.py", line 193, in _run_module_as_main
    "__main__", mod_spec)
  File "c:\python364\lib\runpy.py", line 85, in _run_code
    exec(code, run_globals)
  File "C:\Python364\Scripts\jupyter-book.exe\__main__.py", line 5, in <module>
    main()
  File "c:\python364\lib\site-packages\jupyter_book\main.py", line 10, in <module>
    from .build import build_book
  File "c:\python364\lib\site-packages\jupyter_book\build.py", line 8, in <module>
    from nbclean import NotebookCleaner
  File "c:\python364\lib\site-packages\nbclean\__init__.py", line 5, in <module>
    from .clean import NotebookCleaner
  File "c:\python364\lib\site-packages\nbclean\clean.py", line 4, in <module>
    from nbgrader.preprocessors import ClearSolutions
  File "c:\python364\lib\site-packages\nbgrader\preprocessors\__init__.py", line 1, in <module>
    from .base import NbGraderPreprocessor
  File "c:\python364\lib\site-packages\nbgrader\preprocessors\base.py", line 1, in <module>
    from nbconvert.preprocessors import Preprocessor
  File "c:\python364\lib\site-packages\nbconvert\__init__.py", line 6, in <module>
    from . import preprocessors
  File "c:\python364\lib\site-packages\nbconvert\preprocessors\__init__.py", line 7, in <module>
    from .csshtmlheader import CSSHTMLHeaderPreprocessor
  File "c:\python364\lib\site-packages\nbconvert\preprocessors\csshtmlheader.py", line 17, in <modul
e>
    from notebook import DEFAULT_STATIC_FILES_PATH
  File "c:\python364\notebook.py", line 56
    return b
           ^
TabError: inconsistent use of tabs and spaces in indentation

What do people think about using a Python CLI instead of a Makefile for simple commands? We could define the cli in scripts/ as a mini Python module called jupyter-book. Then, we could use Python to parse args and do stuff.

Right now, to build the book you run make book which calls python/generate_book.py.

Howeever, instead of this, we could instead tell people to first install the CLI with pip (e.g. pip install -e scripts/cli). Then they could run things like

# Generate the book
jupyter-book generate

# Clean the book
jupyter-book clean

# Serve the book
jupyter-book serve

What do folks think? The main reasons for this is that make is fairly annoying to use, and isn't always installed on people's machines, whereas we can probably more easily get people to install Python. Also Python has a much more powerful set of tools for parsing arguments and making a CLI.

Anyone have thoughts on this? Maybe @SamLau95 or @matthew-brett or @TomDonoghue ?

My textbook has the MathJax blocks appear much smaller compared to the MathJax inline portion. A particularly good example if this is [here].(http://prob140.org/textbook/chapters/Chapter_04/04_Updating_Distributions)

How can I scale the MathJax blocks without scaling the inline text?

Wouldn't it be nice if the notebooks folder was a git submodule? And:

1. The summary file was somehow automatically generated from that folders "index.ipynb"
2. The requirements file was generated from the submodules requirements file.

Currently the only way to convert a notebook to PDF uses latex under the hood, which creates many differences in the appearance of the output doc, and also adds some complexity to the build.

Another option would be to explore using javascript libraries to do this...it seems like an HTML element could be converted to PDF using some version of this code:

https://stackoverflow.com/questions/53985512/failed-to-execute-drawimage-on-canvasrenderingcontext2d

It'd be super nice if the auto-generated nav bar on the right-side scrolled down with the page. Probably should be an optional thing that could be set in the _config.yml.

Having so much fun with this thing! It looks great!

From @dcroce: When opening the ipython notebook, the math shows up slightly different. For example the \ to escape the * will show up in the ipython notebook but on the textbook turns out as desired. There are other minor differences too. See 9.3 of the textbook and compare to the notebook for a specific example (New url is http://prob140.org/textbook/chapters/README)

You can only fork a repo once. What happens if you want to write more than one textbook?

Maybe use the GitHub import functionality instead?

I have many blocks of code with a #HIDDEN comment at the top. At the moment, this causes them to not show up when building the website. However, the output also does not show up. Is there a setting (or a way to alter #HIDDEN) so that the code block remains hidden but the output is not suppressed?

In #27 @matthew-brett mentioned that he has a bit of code to allow YAML to exist in the content files. The site build would let you add to this configuration rather than replace it.

We should add this to jupyter-book!

matthew-brett/dsfe@7a089ed

Take this page for example:

https://325-137292803-gh.circle-artifacts.com/0/html/features/hiding.html

Below is how it looks like on (two of) my (Debian) Linux machine running google chrome browser:

you see how the scrollbar gets behind the TOC table. This is also true for pages generated via the current master. However your earlier version of #59,

https://85-137292803-gh.circle-artifacts.com/0/html/features/notebooks.html

does not have the problem:

This is, however, not an issue on my Macbook running chrome. Still it would be great if we could identify the relevant changes in the CSS and fix it for Linux. I can certainly test it for your patches if there is no Linux OS or readily available VM on your end. Thanks a lot!

Currently we're using nbconvert and a custom template to create jekyll-ready markdown files. Now that pandoc supports jupyter notebooks, perhaps we could use it to offload some custom code onto the (much more well-tested and used) pandoc.

Pandoc will convert Jupyter Notebooks to pandoc-flavored markdown, which is pretty close to jekyll-flavored markdown. I think that if we did the pandoc conversion, then ran find/replaces on:

1. ``` {.python} -> ```python

• (or r, or whatever the language was)

2. ::: {. -> ::: {:.

• (since Jekyll classes start with {:.classname, not {.classname

3. ::: ->

• (since the remaining ::: shouldn't be needed.

I think that this would get us the same functionality, including a ton of metadata from the conversion process.

Also, I don't believe that pandoc is difficult to install since it's got binaries available for many languages. Any feedback on that would be great.

The SUMMARY.md file currently up on the repo has numerals prepended on each line item (below [SUMMARY_original.md]). That's handy, and, I think, required to get those to show up in the sidebar as well. However, running python scripts/generate_summary_from_folders ./notebooks --overwrite doesn't reproduce this. Below is an example [SUMMARY.md] of doing that (plus a few changes in the structure that are beside the issue).

[SUMMARY_original.md]

# Summary

* [Quickstart](notebooks/introduction/intro.md)
  * [Adding markdown files](notebooks/introduction/markdown.md)
  * [Adding notebooks](notebooks/introduction/notebooks.ipynb)
* [1. Data Science](notebooks/01/what-is-data-science.md)
  * [1.1 Introduction](notebooks/01/1/intro.md)
    * [1.1.1 Computational Tools](notebooks/01/1/1/computational-tools.md)
    * [1.1.2 Statistical Techniques](notebooks/01/1/2/statistical-techniques.md)
  * [1.2 Why Data Science?](notebooks/01/2/why-data-science.md)
  * [1.3 Plotting the Classics](notebooks/01/3/Plotting_the_Classics.ipynb)
    * [1.3.1 Literary Characters](notebooks/01/3/1/Literary_Characters.ipynb)
    * [1.3.2 Another Kind of Character](notebooks/01/3/2/Another_Kind_Of_Character.ipynb)
  * [1.4 prototype light curve fit](notebooks/01/4/prototype_light_curve_fit.ipynb)
* [2. Causality and Experiments](notebooks/02/causality-and-experiments.md)
  * [2.1 John Snow and the Broad Street Pump](notebooks/02/1/observation-and-visualization-john-snow-and-the-broad-street-pump.md)
  * [2.2 Snow’s “Grand Experiment”](notebooks/02/2/snow-s-grand-experiment.md)
  * [2.3 Establishing Causality](notebooks/02/3/establishing-causality.md)
  * [2.4 Randomization](notebooks/02/4/randomization.md)
  * [2.5 Endnote](notebooks/02/5/endnote.md)
* [3. Programming in Python](notebooks/03/programming-in-python.md)
  * [3.1 Expressions](notebooks/03/1/Expressions.ipynb)
  * [3.2 Names](notebooks/03/2/Names.ipynb)
    * [3.2.1 Example: Growth Rates](notebooks/03/2/1/Growth.ipynb)
  * [3.3 Call Expressions](notebooks/03/3/Calls.ipynb)
  * [3.4 Introduction to Tables](notebooks/03/4/Introduction_to_Tables.ipynb)
* [4. Data Types](notebooks/04/Types.ipynb)
  * [4.1 Numbers](notebooks/04/1/Numbers.ipynb)
  * [4.2 Strings](notebooks/04/2/Strings.ipynb)
    * [4.2.1 String Methods](notebooks/04/2/1/String_Methods.ipynb)
  * [4.3 Comparisons](notebooks/04/3/Comparison.ipynb)

[SUMMARY.md]

* [Programming-in-python](./notebooks/03/programming-in-python.md)
  * [Expressions](./notebooks/03/1/Expressions.ipynb)
  * [Introduction To Tables](./notebooks/03/4/Introduction_to_Tables.ipynb)
  * [Calls](./notebooks/03/3/Calls.ipynb)
  * [Names](./notebooks/03/2/Names.ipynb)
    * [Growth](./notebooks/03/2/1/Growth.ipynb)
* [Types](./notebooks/04/Types.ipynb)
  * [Numbers](./notebooks/04/1/Numbers.ipynb)
  * [Comparison](./notebooks/04/3/Comparison.ipynb)
  * [Strings](./notebooks/04/2/Strings.ipynb)
    * [String Methods](./notebooks/04/2/1/String_Methods.ipynb)
* [Causality-and-experiments](./notebooks/02/causality-and-experiments.md)
  * [Observation-and-visualization-john-snow-and-the-broad-street-pump](./notebooks/02/1/observation-and-visualization-john-snow-and-the-broad-street-pump.md)
  * [Randomization](./notebooks/02/4/randomization.md)
  * [Establishing-causality](./notebooks/02/3/establishing-causality.md)
  * [Snow-s-grand-experiment](./notebooks/02/2/snow-s-grand-experiment.md)
  * [Endnote](./notebooks/02/5/endnote.md)
* [Markdown](./notebooks/introduction/markdown.md)
* [Intro](./notebooks/introduction/intro.md)
* [Notebooks](./notebooks/introduction/notebooks.ipynb)
* [James-intro](./notebooks/01/james-intro.md)
  * [Intro](./notebooks/01/1/intro.md)
  * [Prototype Light Curve Fit](./notebooks/01/2/prototype_light_curve_fit.ipynb)

Currently, the instructions for Jupyter Book require somebody to copy the git repository or fork it. However, this causes a fair bit of confusion and may be problematic if people want to make multiple books.

Another option would be to define jupyter-book as a cookiecutter package that people can quickly populate with their project-specific info. I'm thinking something like:

1. The config.yml file can be populated with cookiecutter inputs
2. There's another cookiecutter input for a path to a folder that contains the book's content. It will then copy that folder into the content/ folder.
3. An option to automatically generate a YAML file with the TOC using the alphanumeric ordering of the content folder. Then users can edit that as they wish to get it right.

This way, you should be able to get up-and-running with jupyter-book more easily, and it might making upgrading easier in the future.

Design spec

From the user's perspective

A CLI is used to manage the creation of new Jupyter Books. Something like

jupyter-book create
  [--version v0.1]  # Specifies a version of jupyter-book
  [--config myconfig.yaml]  # Pre-fill these configuration options
  [--content path/to/content/folder]  # Folder w/ Jupyter Notebooks + markdown files
  [--toc path/to/toc.yml]  # With URLs relative to the content folder
  [--css path/to/custom.css]  # Custom CSS rules to add to the site
  [--js path/to/script.js]  # Custom JS scripts to add to the site

Jupyter-book will then use the cookiecutter python moule to create a new jupyter book project from the template. It will do the following:

1. Create a new project template, pre-filling any fields that are specified in config.yaml and asking questions for the remaining fields using cookiecutter
2. If --content is provided, copy the notebooks in --content to the content/ folder of the resulting repository
3. If --toc is provided, copy the file to the _data/toc.yml file. If --content is provided but not --toc is provided, auto-populate a TOC using alphanumeric ordering of the content folder to help people get started.
4. Choose a license using a hook that is configured with the config.yaml file

In this way, users could upgrade to a new version of jupyter book by keeping their book's configuration file separate along w/ the TOC and then running

jupyter-book create --version <new-version> --config path/to/bookconfig.yml --content path/to/mycontent.yaml --toc path/to/mytoc.yml

The result should be a fully-functioning book that can be run with make book, w/ the latest CSS/JS/etc in the jupyter-book repository.

I know that @arokem likes cookiecutters. Do you think this sounds reasonable? I saw that @gnestor was also commenting in the cookiecutter repo, any chance you have thoughts? :-)

Has anyone tried this? Or is there any known reason why this wouldn't be feasible?

As far as I know, Plotly generates standalone javascript/html as an output in the ipynb, and the instructions here say this but are also a bit vague on if there's other compatibility issues:

Interactive outputs
We can even do the same for interactive material. Below we’ll display a map using ipyleaflet. When the notebook is converted to Markdown, the code for creating the interactive map is retained.
Note that this will only work for some packages. They need to be able to output standalone HTML/Javascript, and not depend on an underlying Python kernel to work.

When doing make textbook I get this traceback:

Traceback (most recent call last):
  File "scripts/generate_textbook.py", line 229, in <module>
    cleaner.clear(kind="content", search_text=site_yaml.get('hide_code_text'))
TypeError: clear() got an unexpected keyword argument 'search_text'
make: *** [textbook] Error 1

It looks like the latest version of nbclean on pypi (0.3.1) doesn't include that search_text kwarg. Came across this when following the tutorial for building a textbook, which uses the proivded environment.yml file, which in turn pulls this older version of nbclean from pypi.

Thanks for the tools!

I have a Jupyter Book that uses notebooks with an octave kernel. These notebooks work as expected on mybinder.org, but not using thebelab (apparently thebelab doesn't use the octave kernel). Am I missing something?

Here is the octave notebook and here the repo.

@choldgraf

As we were talking about, I'd like to do a conversion to the new textbook system. I'd guess it's similar to the previous system of forking and then merging with our current repository, but just wanted to check with you if there was anything else I should be aware of?

Thanks,
Dominic

Hi @choldgraf (and others)

I recently made some commits to fix some latex errors in the 140 textbook. While the commits show up in the repo, the book has not rebuilt and the errors are still there. When I serve the book locally, the errors are gone. We were getting a page build failure, but I'm not sure if it is still there. Would you mind taking a look at https://github.com/prob140/textbook and giving some insight as to why the book is not building?

Thanks!
Dominic

I am trying to change the color of the links that appear in the textbook to match with the sidebar. For example, see http://prob140.org/textbook/chapters/README.

I inspected the links and say the line that controlled the color was main.css.5, which is:
@charset "utf-8";

I'm unfamiliar with css, but a quick google search recommended to not change this. How can I change the colors of these links?

Sorry for this one, but I noticed that syntax-highlighted Python 'None' is invisible in the default theme:

https://matthew-brett.github.io/dsfe/chapters/07/none

I know this question is lazy - but what is the best way to configure to avoid this? Can it be done per-page?

Can I use jupyter-book without GitHub webpage upload or ruby server?

Installing with pip doesn't grab the minimum dependencies found in the requirements.txt (i.e. nbclean is required to create the demo book, but it's not included in the setup.py dependencies).

Would y'all like a PR to add these to the install_requires arg in the setup.py?

An idea that's come up a few times with Data 8 has been the ability to "version" the notebooks. This could be something that others find useful as well.

I'm not sure what would be the best way to support this, however. A few ideas that come to mind:

Support this directly within Jupyter-Book. This would require having multiple folders w/ versions of the book's files. However it'd also require us having multiple TOC files etc.

Perhaps we could have another folder called /versions and another helper script that could be called by something like make version 1.1. This would copy all the markdown in the current "content" folders to a versions/1.1 folder and also add metadata like version: 1.1 to the YAML headers. It'd also change the slugs to have an extra versions/1.1 at the front and would then do the same for the toc.yml file.

Main drawbacks here is that this would add a fair bit of complexity to the build system.

Try to capture this with documentation and "best-practices". E.g., just tell people "you can only have one live version of a book but you can store raw values for versions in git branches".

we don't have a contributing.md document!

Original post/problem below.

There is currently a bug that causes the Thebelab kernel config setting (kernel_name) to not be refreshed/changes relative to the initial page the user accessed the Jupyter Book on.

This issue was discovered (for me) because the initial landing page in the template (content/intro.md) is not an ipynb, so when the (_build/intro.md) file is built, the kernel_name config value is not set. Due to a recent contribution, pages with no kernel_name set in their configs start Thebelab using python3. So for me, since all my notebooks were not using the python3 kernel (I was using SoS) , every user landing on the home page first were not using the right kernel to run the Jupyter Notebooks later one when browsing the other pages. A page reload would fix this issue (if on a page that was build using an ipynb), presumably because this would clear the cache and initiate a new Thebelab session (this time, on a page that has the proper kernel_name setup).

(original post)

I'm not sure which tool is the culprit here, so I'll start by posting my issue here at the top and work my way down.

I'm using Jupyter Book, the Thebelab feature, MyBinder, a Dockerfile, and the Jupyter Notebooks are running on the Script of Scripts kernel for multi-language support.

This issue is reproducible, I've done it several times in a row. It happens for other UX "pathways", not all, but for the sake of simplicity I will describe the simplest here.

The gist of the issue is that, the first time a user (that's me!) loads a Jupyter Book chapter, then tries to run a Thebelab cell, the magic command at the top of the cell (used/required by the Script of Scripts Jupyter kernel to indicate which language needs to be used for that cell, e.g. %use octave, %use sos (actually means python3)) is either not executed, not recognized, or something else. Or, the jupyter book isn't opened using the SoS kernel. This causes an error (for my case, since the first cell is some Octave/Matlab code, the an error is thrown I think because it still thinks it's in a python environment and can't read the Matlab syntax).

HOWEVER, if I simply immediately reload the web page, and follow the same steps, the kernel is loaded fine, and the cells execute without issue.

I took two videos of me reproducing this issue:

Video 1: https://www.youtube.com/watch?v=aeiB_LB2Q6w&feature=youtu.be

Video 2: https://www.youtube.com/watch?v=P0B9Zqr886Y&feature=youtu.be

Note that, I don't encounter this behaviour if I try running the cells within a separate MyBinder session (not Thebelab).

To replicate the steps exactly:

1 - Start at the landing page : https://qmrlab.org/t1_book
2 - Click the "Signal Modelling" page under "Inversion Recovery"
3 - Click the "Interact Inline" button.
4 - Go down to the first cell (starts with %use octave), and click run
5 - (optional) Since the first cell isn't supposed to have any output and only the second one does, click run on the second cell too (starts with %use sos)
6 - You should have encountered errors for both cells.
7 - Immediately reload the page.
8 - Follow steps 3-5, and a plotly figure should appear after the second cell after a minute or so.

Repo: https://github.com/qMRLab/t1_book
Github is setup to generate the site off of the gh-pages branch: https://github.com/qMRLab/t1_book/tree/gh-pages

Hi @choldgraf and team !

Thanks so much for making jupyter-book -- it's a really exciting initiative ! I'd like to cite it, but I can't seem to find the best way to do so. It looks like you already have releases -- are you using Zenodo to generate DOIs ? Or is there another [paper, poster, etc] that would be better to cite ?

Thanks again !

Elizabeth

A common pattern in websites is to set all permalinks to be lowercase-with-hyphens. However since we're building permalinks from file paths, perhaps we don't want to force the files themselves to have this structure.

We could get around this by:

1. Automatically re-directing from the lowercase-permalink structure to whatever the file path capitalization etc
2. Automatically re-directing from whatever the file path capitalization is to lowercase-permalink (effectively forcing all pages to have a lowercase-permalink style URL.
3. Not addressing this at all

Anyone have thoughts on that? (cc @SamLau95...one of the main reasons for this is because the Data 8 textbook has mixed these two patterns over the years)

from @TomDonoghue in the previous version of this repo:

Possible small feature addition - happy to make a PR if this seems interesting:

As I was using this for a course website, I first wanted to remove the 'Interact' button, and then add a 'Download' button (to directly grab the notebook from the site).

So, I added Button options are at the top of the config, for a group of 'buttons' I might use at the top of the rendered notebooks (and associated code to make them work through the repo):
COGS18/COGS18.github.io:_config.yml@master

^I'm not sure what set of buttons one might want to support in the base version, but I think at least a toggle for having the 'Interact' button might be nice (and implies one can easily extent for others), and maybe downloads too (I also have a pdf button that is probably much more idiosyncratic).

Sanity check - features comments / things should go here, and not the demo notebook? Also, my course textbook is private right now but you two (Sam & Chris) should have invites, if you want to have a look.

This tool overlaps conceptually quite a bit with bookdown, another OS tool for online books from markdown. We should make sure to mention it somewhere in the intro as another option for people

Once #54 lands, it'd be great if we can find a way to highlight the currently-active section on the right side.

Something like this should do the trick:

https://stackoverflow.com/questions/36110223/highlighting-current-section-on-scroll-gap-between-sections

we just need to make sure we don't chew up too much CPU

@SamLau95 made some great modifications to the DS100 textbook using the jekyll build for inspiration. Here's a short wish-list of things we could port to this repository:

wish list:

• Automatically insert nbinteract buttons DS-100/textbook@e155594
• Adding TurboLinks
  • DS-100/textbook@edec380
  • DS-100/textbook@6cfe3fe
• Navigation w/ left and right keys DS-100/textbook@60838bd
• Sidebar toggling: DS-100/textbook@b076a97
• Sidebar styling + window layout behavior: DS-100/textbook@fcd37a0

I added a script to my repo to generate an ordered summary, but now my generate_textbook.py cannot find the README.md, and thus is giving an error. I only added extra files to the scripts folder, so I'm not sure why it would be related. Was their an update to the generate_textbook script that could be causing this?

https://github.com/dcroce/textbook-jekyll-template/

Using an example from the jupyter-book demo,

there is a leading white space in the line purchase_price. This also happens in my other code blocks. It is bothering at least to me (and possibly to Python programmers). Would be nice to have it removed.

A previous version of Jupyter Book added support for nbinteract, an interesting project from @SamLau95 that facilitated interactive visualizations using Binder. It's similar to Thebelab, though focused around creating interactive widgets instead of editable code cells.

I'd like to see Jupyter Book support nbinteract once more - @SamLau95 do you have guidance on the path-of-least-resistance to doing this? I'm thinking:

• Adding the HTML for the button here: https://github.com/jupyter/jupyter-book/tree/master/_includes/buttons
• Adding an nbinteract.js that is called from the button: https://github.com/jupyter/jupyter-book/tree/master/_includes/js
• Adding some docs to explain how to use nbinteract (probably largely linking out to your site)
• Exposing some basic configuration for nbinteract in _config.yaml (maybe co-opting the binder config)
• Adding an example that uses nbinteract

What do you think?

I've created some interactive brain images using nilearn's plotting calls to brainsprite.js. The images look lovely in a jupyter notebook, and when I render the notebook with nbconvert they still look lovely and retain interactivity. But when I try to put the executed notebooks into jupyter-book, I get an unrendered iframe:

Any ideas what could be going on here, or how to start tackling this ? Thanks as always !

Is there any way (or any plans) to implement a search bar? It would be nice to search for keywords throughout the textbook.

In a recent twitter thread, @jph00 and @damianavila suggested that Nikola might be a good option for a project like Jupyter Book. Others have also suggested that either Hugo or Gatsby is a good choice. This is an issue to keep track of whether this is worth pursuing.

Feel free to add to either of the lists below.

Reasons for changing

• Jekyll is fairly slow (it takes many seconds to build a site or update after content is changed for non-trivial-sized books).
• Ruby is a gigantic pain to install and has a very different experience on different operating systems.

Generic downsides

Some general challenges that would come with a new SSG

• An up-front cost of switching over the templates / config / build / documentation to nikola instead of jekyll
• Another confusion cost of changing the usage pattern for users
• Users would now have to build the raw HTML and host that online (e.g. with gh-pages or netlify). gh-pages would no longer auto-build for them
• We'd lose some plugins like jekyll-scholar, for which nothing like this exists in nikola

SSG-specific pros

Hugo

• Super easy to install
• Has a book theme already built in: themes.gohugo.io/hugo-book demo here
• Has pandoc conversion support (but I'm not sure how to use it exactly...)

Gatsby

• React seems super cool (though I don't have much expertise)
• Nteract has a lot of great react work done with notebook interfaces (https://components.nteract.io/) and will probably continue improving this
• There is already an ipynb transformer for Gatsby (https://www.gatsbyjs.org/packages/@gatsby-contrib/gatsby-transformer-ipynb/)
• this is probably the most useful skillet to learn from a web UI standpoint...

Nikola

• It can use Mako for templating, instead of liquid, which could potentially result in cleaner templates etc.
• It uses Python, which more people in the jupyter ecosystem already know
• Nikola also has first-class jupyter notebook support
• It looks like porting from jekyll would be really easy