Support blogs

[ddanieltan]

Many projects use their documentation or projects site as blogs as well. Jupyter Book has no inherent blogging functionality, and some lightweight features could make this really useful.

Example minimal blogging features:

• A way to display a list of blog posts
• An RSS feed for blog posts

Nice to haves that may not be required:

• Tags and categories, with sub-feeds for each
• Tag and category clouds etc

To Do

• [ ] Investigate example blogs to see how they did this (e.g. https://github.com/jupyter-book/blog)
• [ ] Pick one that feels the best and either refine its method or agree it's good enough to recommend
• [ ] Document it in the Jupyter Book docs

---

Old to do list from Sphinx / JB1:

- [x] Investigate blogging options with the Sphinx ecosystem (potentially [ablog](https://ablog.readthedocs.io/))
- [ ] Document how one could use `ablog` to blog with Jupyter Book (e.g., how to configure the config.yaml properly) ([here's how we use ablog in our website](https://github.com/executablebooks/meta/blob/master/docs/conf.py#L33), which uses Sphinx directly, but this config could be used in Jupyter Book similarly)
- [ ] Decide if the documentation is complex enough that it warrants us building some kind of feature flag around.

[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.

[chrisjsewell]

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

Note in ablog we have now added this feature. For example I am using ablog, with myst-parser and sphinx-book-theme, here: https://quantum-mobile.readthedocs.io/en/latest/releases/index.html

[choldgraf]

@chrisjsewell I think that ABlog is a nice-enough solution that for now we should just document how to do "blogs with Jupyter Book via ABlog", and see if that is simple enough that we don't need to build any infrastructure for it specifically.

[dclong]

A plugin (enabling converting notebooks using jupyter-book) for Pelican would be awesome!

[ddanieltan]

Hi thread, I'm the OP here. It's been a while since I took a look at this thread and I'm pleasantly surprised to see that many others are also interested in building a blog from this library.

Since I didn't see it mentioned in this thread, I want to point out that @choldgraf has documented how he rewrote his blog with Sphinx and EBP tools here: https://predictablynoisy.com/posts/2020/sphinx-blogging/

After reading his post, I kinda realized that to create a blog, I did not need new features to jupyter-book per se. Rather, I just needed to better understand how to use all the other libraries under the EBP's (https://executablebooks.org/) ecosystem.

Lastly, I adapted Chris's example for my own blog, and I just wrote a how-to post here. Writing that post is actually why I thought to dig up this thread again...

Hope these resources help you figure out the right tooling for your personal blog.

[eidorb]

Hey @ddanieltan, your personal domain seems down at the moment.

You can still read the post hosted on GitHub.

Lastly, I adapted Chris's example for my own blog, and I just wrote a how-to post here. Writing that post is actually why I thought to dig up this thread again...

[ddanieltan]

@eidorb Thanks for calling this out!

As always I'm tinkering about with my blog at the moment, and in the interim I decided to take down my personal domain. Also as you rightly point out, the github.io version is still up.

For posterity, if I ever choose to reclaim my github.io namespace for my new blog project (pretty likely), my code on how to get an EBP-ecosystem blog up and running will continue to be accessible here: https://github.com/ddanieltan/blog_ebp_sphinx_starter

[bsipocz]

https://blog.jupyterbook.org/ is now built on top of JB(2), so I believe we can close this issue. Please reopen if you think this is incorrect.

(repo is here: https://github.com/jupyter-book/blog)

[choldgraf]

My feeling is that we should keep this one open until there's at least a "recommended" way of accomplishing blogs with Jupyter Book / MyST. The Jupyter Book blog currently uses its own custom plugin for this, so I think that's not quite useful enough for others to consider this one done.

I suggest that we consider this issue done when there's a section in our docs that gives users guidance for how they can accomplish blogs with a JB/MyST site. This could be built-in functionality, or a plugin, or listings etc - but we should at least mention a recommended way to accomplish this.

I updated the top comment with an updated to-do for the JB2 days!