Jupyter-book: [ENH] Add Tufte style

[darribas]

It'd be really cool to have an option to set up a book using the Tufte layout. The font is beautiful and the layout is designed for better reading of scientific documents.

Technically speaking, I'm not sure how hard it'd be to wire into the current structure of jupyter-book but a good place to start could be tufte-css and maybe the Tufte-inspired Jekyll theme?

[choldgraf]

I think it'd be really cool! @emdupre also mentioned theming as something she'd like to see too. I think the trick would be pulling out the right CSS rules so that we can make them more modular and can switch between different CSS files depending on the style we want

[choldgraf]

A quick follow-up question:

Do you imagine the CSS and layout changes would exist within a single page? Or would they need to be applied to the entire site? The former is much easier than the ladder :-)

Thinking about this more, we could do a few things:

1. Take a look at the tufte CSS demo and make sure that we have design elements that map onto all of the things there (e.g. side quotes, block quotes, etc). We could manage those either with tags in the Jupyter Notebook, or with some kind of special syntax (e.g. {% blockquote %}?)
2. Add support for _themeing_ in Jupyter (see https://github.com/jupyter/jupyter-book/issues/262)

note: there's also a hugo Tufte CSS theme

[darribas]

Hey! Thanks for following up. I'm not sure about the difference but my sense is you could envision implementing this on a single page and then have some way of making every notebook/md in a book get that applied? I have very little css expertise, but I was thinking the tricky thing would be to merge the Tufte guidelines (footnotes, wide and non-wide images, etc.) with the cool bits of jupyter-book like the built-in index of a page, the toggle-on/off of the book menu, etc.

[choldgraf]

yep - I think that figuring out the challenges in _structural_ elements (e.g. footer, sidebar, etc) and figuring out the challenges in _design_ elements (e.g., font type, colors, etc) will be two separate things. IMO the structural stuff will be trickier than the design stuff.

[darribas]

Even just the design stuff as an option would be a great additionl. Call me font geek, but that font is a thing of beauty to read...

[choldgraf]

Just a note here that we've now got two of the main structural elements from the Tufte style in Jupyter Book: sidebar content and full-width content. Footnotes etc will require us to support some new markdown syntax which should get more community input before we adopt something. @darribas - what other kinds of things do you imagine adding for Tufte?

[darribas]

Amazing! On top of that, I'd say, some demo/example on how to easily switch the font of a jupyter-book project (I imagine it's just standard css, but would help newbies like me) so one could use the Tufte fonts, which are open and beautiful...

[choldgraf]

Actually, the font is a bit complicated, as I believe it is a Tufte-specific font that is defined in the Tufte-CSS repository. I'd be +1 on a pattern that made this possible though!

[amueller]

I'd be specifically interested in footnotes or sidebar notes. Should this be a separate issued?
Given the possibilities to have side-bars, I think it would be a nice option to have the footnote optionally in the sidebar instead of at the bottom. You could obviously do that manually by adding a number to the text and then adding the number to the sidebar but then you need to keep track of the numbers. Or I guess you could use stars and crosses etc?

In case my description was unclear:

[choldgraf]

@amueller totally agree. The footnotes are already working (though if they aren't clearly documented, let me know and I can add them in somewhere EDIT: nope they weren't documented, I added a section on them here), so I think the trick is just the sidebars.

Does anybody know of a standard markdown syntax for sidebars? It exists for footnotes but I haven't seen sidebars before. Otherwise we'd need to write our own role and directive and ask people to use that

e.g. something like:

in-line with text would be {side}`my_label`

and then underneath it would be

` {side} my_label
My sidebar text

````

Alternatively, I wonder if we could just add a `:label:` option to the `{margin}` directive. Then we could do

````
Here's text and ref to a sidenote {ref}`mylabel`

```{margin} mylabel
Some margin text

And it would put the label into the text, e.g. [mylabel] ?

[choldgraf]

@amueller wanna open an issue specifically about sidenotes so that we can keep track of it? I feel like embedding it in a general issue about tufte will make it hard to keep track of

[asmaier]

Maybe RMarkdowns Tufte style can be an inspiration. I think it is beautiful:

https://rstudio.github.io/tufte/
https://github.com/rstudio/tufte/blob/master/inst/rmarkdown/templates/tufte_html/skeleton/skeleton.Rmd

It even allows plots in the side notes.