Handle the notebook title and metadata header

[maximlt]

Each page of the gallery is built 1) by adding a heading from the notebook's name (can be normalized), 2) by adding links to download or execute the project in a deployment, and 3) by embedding the full notebook content. If the full notebook includes a title, the page will then have two titles. For instance:

As it should be possible for users to download and execute the notebooks, it makes sense for them to have a title. Solutions include:

• all the notebooks should have a first title cell, that is then stripped off during the build
• all the notebooks should have a first title cell, and then the build somehow injects the download links after that cell

[jbednar]

I believe there are already issues discussing this topic, either in this repo or in nbsite's repo. Indeed, those are the main options that make sense, and I favor the second one, but don't know how to achieve it. There's also a third option, to put the download link at the very top, but use formatting so that it makes sense to be above the title (e.g. italics or some other formatting that makes it clearly "meta", i.e. about the page, rather than part of the content of the page).

[maximlt]

The other HoloViz galleries (Panel, HoloViews, etc.) are built from notebooks that do not have a title, it's added part of the build process.

Your third option is interesting and could work well for this website.

Ultimately this is about the conversation we are meant to have about how to handle the examples across HoloViz. I just wanted to record this issue as it doesn't look so good on some pages here, and projects have a name in their anaconda-project.yml file, which makes it different from the other galleries.

[maximlt]

The more I think about it the more I like your third option. The only difficulty that we may have is Sphinx complaining about a page not starting with a section title. If it does, we could just ignore it.

I was thinking more about it as this could also be leveraged to display the projects metadata. Last year some metadata was added at the beginning of most notebooks:

The info in there is a little redundant with what is declared in the project:

• Written by in the notebook for a maintainers list in the project config
• Created in the notebook for a currently optional created entry in the project config

Last updated is only in the notebook, it's not in the project config, but it's something we could of course add in there and actually easily generate automatically.

My suggestion would be to have the source of truth for the metadata be the project config only (the anaconda-project.yml). We could then leverage that metadata to create a header that would be displayed above the notebook title on the website, displayed however we like. Having that information in the project means that it could be leveraged more easily to improve the gallery page. Streamlit for instance displays the authors list:

(In a very fancy world, the gallery items could be sorted by their Last updated date.)

I can see two drawbacks to this:

• projects that have multiple notebooks will have the same Last updated date. There aren't many projects with multiple notebooks.
• Users that will download the notebook archive or run the notebooks on the read-only deployments will not see that info as they will be delivered the original (header-less) notebook. To cope with that we could 1) dynamically generate the project README.md file to embed that medatada and/or 2) inject this metadata in a nice formatted way in the first cell of the notebook (shouldn't be too hard).

@jbednar let me know what you think about that.

[jbednar]

Wow, that sounds great! I'm not too concerned about people who download the notebook locally; it's fine for only the website to show the metadata, and for downloaded users to see it only if they look at the anaconda-project.yml. So I'd vote against injecting into the README or the notebook, to keep things simple!

[maximlt]

This has been implemented.