Jupyter-book: Support blogs?

[ddanieltan]

I totally get that this is the jupyter book project, and my first usage of this project has been to create online textbooks (which has been a fantastic experience). It occurred to me that all the great things about jupyter-book:

• jupyter notebook specific CSS
• Tufte-like features
• not relying on Jekyll engine
• MyST markdown
• glue to easily cross-reference images and figures
  Would also be great features for a python blog primarily built with jupyter notebooks.

So was I was just wondering if there's a possibility for an adaption of the current jupyter book project to also support blog building? Perhaps with a specific blog html theme?

[chrisjsewell]

Thank @ddanieltan I certainly don't think its beyond the realm of possibility 😄

Apart from the theme, is there any other differences in the process you could think of, e.g. how would you envision hosting this blog?

[ddanieltan]

For hosting, I think the current process of jupyter-book build is fine. Ie. the package just needs to build and output the static files and the user can decide how to host them

1 thing which I couldn't quite figure out a smart solution for is how to handle a blog whose posts eventually grow to a large amount. It would, for example, impact how the navbar HTML is built. For a blog with 50 posts, I probably don't want the user to see all 50 posts in the navbar. That's probably the key issue preventing me from using the jupyter-book package as is to build a static blog now.

[chrisjsewell]

Thanks, good point.

Well I can't promise that we will get round to this in the immediate future (PRs welcome 😬), but certainly if you have any more thoughts on it post them here.

Also, for anyone else reading this, remember that you can "upvote" this issue, to maybe bump it up our priority list!
(see https://executablebooks.org/en/latest/feature-vote.html)

[choldgraf]

I think that the main difference between a "blog" and our current implementation of Jupyter Book are basically:

1. A "special" kind of file that is a blog post
2. A way to show these posts sorted by date
3. A way to show snippets of these posts (e.g. 4 latest blog posts)
4. Maybe some kind of special sidebar treatment

I think these would be the main things

[oddrationale]

Maybe there's a way to integrate blogging through a Sphinx extension? Haven't tried it yet, but one that I found is ABlog. It uses a post Sphinx directive to turn any page into a blog page.

[oddrationale]

Also worth mentioning is fastpages which is a blogging system based on Jupyter Notebooks. It uses a different ecosystem than Jupyter Book, Jekyll instead of Sphinx. But also worth checking out.

[choldgraf]

Ablog is actually quite nice! I just checked it out and it seems pretty well-featured. Perhaps that's a good foundation for us. @chrisjsewell I assume aiida has a blog, what do y'all use?

[chrisjsewell]

I assume aiida has a blog

Yeh but we don't do it via sphinx; aiida.net uses wordpress

Maybe there's a way to integrate blogging through a Sphinx extension

Indeed ablog looks promising (see https://github.com/executablebooks/meta/pull/129).
I think we should look to integrate it more with jupyter-book though.
In the same way that we don't use the toctree directive, in place of the _toc.yml, we could look to replace its post directive with a dedicated key in the _toc.yml, something like:

- blog: path/to/blogs-*

where the * is a wild card, possibly for the date(time):

path/to/
  blogs-2020-08-07.md
  blogs-2020-08-08.md
  ...

It would also be ideal if we could utilise Markdown top-matter, in place of the directive options:

---
tags: earth, love, peace
category: python
author: me
---

# My Post

[choldgraf]

@chrisjsewell yeah I agree eventually we should find a way to "short-cut" the configuration of whatever blogging engine we use. I imagined that in the meantime, people could get the same functionality by following just a couple of steps which we could document via a blog post, discussion post, etc. Eventually this could be replaced with some more opinionated jupyter-book-specific config

[chrisjsewell]

I think maybe lets just consolidate what we have for a few weeks, and close some bug issues, before introducing a whole new feature 😉

[choldgraf]

that's my point - for now we should just say "hey all this is how you can accomplish this with manual sphinx config in jupyter book" so that people know how to do it without waiting for a new feature.

E.g. with Binder we've used the Jupyter forum for this - just write up a 'how to' post there, and leave it as a resource for others. Over time if it seems like there's a clear "right" pattern then consider implementing it as a feature.

[dclong]

pelican is a static site (blog) generator which supports jupyter notebooks via plugin. However, I do feel jupyter-books does a much better job in many details such as theme, rendering, code cell copy button, etc.