jupyter-book
jupyter-book copied to clipboard
executablebooks
[ENH] Add Tufte style
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?
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
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:
- 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 %}?) - Add support for themeing in Jupyter (see https://github.com/jupyter/jupyter-book/issues/262)
note: there's also a hugo Tufte CSS theme
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.
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.
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...
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?
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...
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!
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:
@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]` ?
@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
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.
Just wanted to ping in that @patrickmineault might have some ideas / resources, here !
I have a working stylesheet for jupyterbook that patches the main stylesheet with tufte.css, and does some adjustments. It's also dark mode compatible. Regular:
Dark mode:
I can package it up there's significant interest.
Yes this would be awesome! Do you think it's better as a separate package, or is the CSS minimal enough that we could include it here with a switch or something?
That's a good question, how did you think generally about theming in the context of jupyterbook? Do you support sphinx themes or is there another mechanism?
Dark mode is built in to tufte.css, though it required a bit of a patch job to make compatible with jupyterbook styles.
On Thu, Sep 23, 2021, 8:35 PM Chris Holdgraf @.***> wrote:
Yes this would be awesome! Do you think it's better as a separate package, or is the CSS minimal enough that we could include it here with a switch or something?
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/executablebooks/jupyter-book/issues/255#issuecomment-926260182, or unsubscribe https://github.com/notifications/unsubscribe-auth/AA22Q6YCIUEZYFT37YDRDUDUDPBV5ANCNFSM4IKJEKVQ . Triage notifications on the go with GitHub Mobile for iOS https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675 or Android https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub.
other sphinx themes will definitely work - though some might work differently because Jupyter Book does some "configuration translation" in its builds. However, if you're building off of the book theme, then it should "just work".
If you had to reconfigure some of the templates, it might be easiest to just publish it as "sphinx-book-jekyll" or something like that? But if the diff wouldn't be too big, I'd be fine trying to get it in this theme and having a feature flag like
html_theme_options = {
"style": "tufte",
}
cc @mmcky who also had some thoughts on the theming story in Jupyter Book
Oh this tufte theme looks cool. 👍
We have developed a theme for jupyter-book for the quantecon lecture projects which is called quantecon-book-theme. In putting that together we have tried to set it up to inherit from sphinx-book-theme (the default theme in jupyter-book) so might be a handy reference. (cc: @AakashGfude @DrDrij)
We are hoping to turn some attention soon (~~Oct/Nov~~ TBD timeframe) to writing up some documentation on setting up a theme for jupyter-book (and documenting what elements are required and optional, such as margin notes etc.) and perhaps we can put together a theme cookie-cutter style template package for getting started.
Hey folks, reviving this thread. I have the tweaked style spread across two repos:
https://github.com/patrickmineault/codebook
and:
https://github.com/patrickmineault/sphinx-book-theme
You can see the result live here:
https://goodresearch.dev/
What I'm thinking is that one could pull all the changes from the first repo to the second repo to create a custom theme. Then we'd need to add a little bit of piping so that one could configure jupyter-book to use this theme instead of the default. How does that sound?
@mmcky any update on custom theming documentation? My patch to the base jupyter book theme turned out to be short-lived: an update to sphinx-book-theme broke it. I had to downgrade jupyterbook and sphinx-book-theme, and I'm assuming my method of updating the theme is still quite brittle. Ideally, I'd like to reimplement a tufte theme according to best practices so it has a longer shelf life.
hi @patrickmineault it has taken longer than we anticipated. @AakashGfude has been looking at various base options for jupyter-book (such as sphinx-basic-ng) to get an understanding of which to choose as the jupyter-book base theme so that we can then standardize on tags across the project. He will be doing some more work on this later this month, but the documentation is probably (still!) in the medium term once the base has been decided upon.
https://github.com/executablebooks/meta/issues/576
I share your pain with the updates (at the moment) as sphinx-book-theme changes we also update quantecon-book-theme but we have tried to adopt an inheritance model on that project that @AakashGfude knows more about.
@mmcky any update on custom theming documentation? My patch to the base jupyter book theme turned out to be short-lived: an update to sphinx-book-theme broke it. I had to downgrade jupyterbook and sphinx-book-theme, and I'm assuming my method of updating the theme is still quite brittle. Ideally, I'd like to reimplement a tufte theme according to best practices so it has a longer shelf life.
This
is what I get now using a standard installation of
- https://github.com/executablebooks/jupyter-book (installed via
pip install jupyter-book) - https://github.com/patrickmineault/codebook/blob/main/docs/_static/tufte.css
- https://github.com/edwardtufte/et-book
- see also : requirements.txt
