Content authors can add schema.org, OpenGraph, and Twitter Cards metadata

• Book-level metadata (defaults?)
• Page/Chapter/Section-level metadata (overrides?)

Describe alternatives you've considered

is it already possible to include raw HTML? Front-matter metadata would be more user-friendly

Additional context

• This PR links to specs and demos how to add metadata to raw HTML pages: "DAT: Schema.org, OpenGraph, Twitter Cards" https://github.com/CodeForAntarctica/codeforantarctica.github.io/pull/3
• Here's one way to hackishly add "Book-level" metadata to Sphinx docs: https://github.com/wrdrd/docs/blob/master/docs/conf.py#L305 def configure_meta_tags()
• Thing > CreativeWork > Book
• Thing > CreativeWork > ScholarlyArticle
• Thing > CreativeWork > LearningResource
  • https://schema.org/teaches
  • https://schema.org/assesses
• https://schema.org/partOf
• https://github.com/westurner/sphinxcontrib-rdf/wiki/Roadmap
• "List relevant [nbgrader] exercises by associating concept URIs with books/pages/headings and exercises" https://github.com/executablebooks/jupyter-book/issues/881

To complete this

This should be completed by deciding how to add support for the sphinxext-opengraph extension. This Sphinx extension will include opengraph metadata on all pages.

Two options:

1. Natively support it via a config section like:

   opengraph:
       title:
       image:
       ...
   

2. Document how to manually enable this via Sphinx configuration in _config.yml

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

Some of this we already have (e.g. open graph social previews) but it would be great to auto-generate better linked data metadata fields that we can reasonably assume given the information that users put into their books 👍

Can we turn this issue into a list of the most-useful or most-common metadata pieces that we should explore using?

I couldn't find mentions of open graph social previews in the documentation.

I just enabled this with sphinxext.opengraph and a config like this

sphinx:
  extra_extensions:
  - sphinxext.opengraph
  config:
    ogp_site_url: "https://cranmer.github.io/stats-ds-book/"
    ogp_image: "https://cranmer.github.io/stats-ds-book/_static/logo.png"
    ogp_description_length: 200

But that doesn't provide page-level metadata.

very cool! I didn't know about that extension. Right now we are hard-coding some of this in the theme, but it'd be great if we could instead punt this over to this extension if it added the right metadata.

@cranmer thanks for sharing that, did you find a way to add page-level metadata?

Hi there,

The Bioschema.org has released a draft for Training Material: https://bioschemas.org/profiles/TrainingMaterial/0.9-DRAFT-2020_12_08/

Thought it was relevant to this thread.

In the project I am involved in, we build on the legacy jupyterbook and are about to migrate to the new, sphinx based version. Curious to discuss a jupyterbook template for schema.org json-ld could be customised or aligned to this bioschema profile.

With the legacy book, we edited the _includes/metadata.json file

For page-level linked data / structured data:

• You can return structured data from a Jupyter notebook by implicitly or explicitly display()-ing objects with repr methods:
  • _repr_json_() (JSON-LD)
    • <script type="application/json">
    • <script type="application/ld+json">
  • _repr_html_() (RDFa)
• You can return linked data from zero or more cells individually
• You can build a dict of JSON-LD with the notebook at display it in the last cell (which won't execute or display if there's an uncaught exception earlier in the notebook)
• "Add JSONLD @context to the top level .ipynb node" https://github.com/jupyter/nbformat/issues/44#issuecomment-759861977
  • This may be almost possible to do backward-compaitibly with nbformat with JSON-LD 1.1

See this new functionality in myst-parser: https://myst-parser.readthedocs.io/en/latest/using/syntax.html#setting-html-metadata. (note this version of myst-parser is not yet part of jupyter-book v0.9, but will be in v0.10)

https://myst-parser.readthedocs.io/en/latest/using/syntax.html#setting-html-metadata :

Setting HTML Metadata¶ The front-matter can contain the special key html_meta; a dict with data to add to the generated HTML as <meta> elements. This is equivalent to using the RST meta directive.

HTML metadata can also be added globally in the conf.py via the myst_html_meta variable, in which case it will be added to all MyST documents. for each document, the myst_html_meta dict will be updated by the document level front-matter html_meta, with the front-matter taking precedence.

• [ ] DOC: Template/Examples of how to specify both OpenGraph and Twitter Cards metadata in <meta> tags within <head>
• [ ] ENH: How to specify schema.org metadata once and generate OpenGraph and Twitter Cards metadata (for search indexing and social share cards)
• [ ] ENH: how to append a script(type=application/ld+json) to e.g. doc.body that will be rendered as <script type="application/ld+json" id="abstract hypothesis premise conclusion further study">

Regarding sphinxext-opengraph, what is meant by page-level metadata? sphinxext-opengraph autogenerates og:url, og:title, and og:description on a per-page level.

I'd call that page-level metadata. Some way to specify an og:image would be cool too. https://ogp.me/

This would be really useful!

Is anyone successful at setting a custom description for a page from within Jupyter Notebook? I tried various things for trying to set ":og:description:" without success. This extension seems to snarf up whatever is the first text on the page. If I put content in a zero height div, it was displayed but not used to set the description.