Mkdocs-material: Structured Data, Facebook Open Graph and Twitter Cards support

[yogeshbeniwal]

This is a feature/enhancement suggestion for this theme.

It will be good to enrich page with below listed metadata:

Structured Data: https://developers.google.com/search/docs/guides/intro-structured-data. Preferably Organisation, Website, Article and Author
Facebook Open Graph: https://developers.facebook.com/docs/sharing/webmasters#markup
Twitter Cards: Twitter Summary Card with large Images https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/summary-card-with-large-image

[squidfunk]

Thanks. Could you post in this thread which tags you exactly would like to integrate?

EDIT: Actually, this is what the extrahead template block is for. You could easily extend the base template and insert all tags that are relevant, see http://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks and https://squidfunk.github.io/mkdocs-material/customization/#overriding-template-blocks

[yogeshbeniwal]

For the start and how mkdocs is being used for documentation, I recommend below tags

Schema and Structured Data using JSON-LD

1. Author: http://schema.org/author
2. Organisation: https://schema.org/Organization
3. Person: https://schema.org/Person
4. Website: https://schema.org/WebSite
5. Article: https://developers.google.com/search/docs/data-types/article
6. Book: https://developers.google.com/search/docs/data-types/book
7. Breadcumb: https://developers.google.com/search/docs/data-types/breadcrumb

Structured data as seen by Google can be validated on https://search.google.com/structured-data/testing-tool

Facebook Open Graph

1. og:url
2. og:title
3. og:description
4. og:image
5. fb:app_id
6. og:type: article, book, books.author and books.book
7. og:locale

Details are at https://developers.facebook.com/docs/sharing/webmasters#markup and can be tested at https://developers.facebook.com/tools/debug/

Twitter Cards: Twitter Summary Card with large Images

1. twitter:card
2. twitter:site
3. twitter:title
4. twitter:description
5. twitter:image

More details at https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/summary-card-with-large-image and can be tested at https://cards-dev.twitter.com/validator

[max-ci]

This is what I'm using in my docs. I think every site is different and it will be hard to make it universal.

<!-- Extrahead -->
{% block extrahead %}

  <meta property="og:url" content="{{ page.canonical_url }}">
  {% if page and page.meta and page.meta.title %}
    <meta property="og:title" content="{{ page.meta.title }}">
  {% elif page and page.title and not page.is_homepage %}
    <meta property="og:title" content="{{ page.title }} - {{ config.site_name }}">
  {% else %}
    <meta property="og:title" content="{{ config.site_name }}">
  {% endif %}
  <meta property="og:description" content="{{ config.site_description }}">
  <meta property="og:image" content="path/to/image.jpg">
  <meta property="og:image:alt" content="Image alt">
  <meta property="og:image:type" content="image/jpeg">
  <meta property="og:image:width" content="1200">
  <meta property="og:image:height" content="630">

  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@username">
  <meta name="twitter:creator" content="@username">
  {% if page and page.meta and page.meta.title %}
    <meta property="twitter:title" content="{{ page.meta.title }}">
  {% elif page and page.title and not page.is_homepage %}
    <meta property="twitter:title" content="{{ page.title }} - {{ config.site_name }}">
  {% else %}
    <meta property="twitter:title" content="{{ config.site_name }}">
  {% endif %}
  <meta name="twitter:description" content="{{ config.site_description }}">
  <meta name="twitter:image" content="path/to/image.jpg">
  <meta name="twitter:image:alt" content="Image alt">

{% endblock %}

I'm not experienced in schema.

[squidfunk]

So after thinking about this I decided not to implement it. Actually, before Material offers extensive variables in the extra namespace I would encourage everyone wanting to use Open Graph features to extend the theme and define the extrahead block, because there is a lot of static data that must just be set and mapped globally. A lot of branching would be necessary, as for the open graph title like it already is with the site title (see @makshh example above). Also tags like *:image:alt etc. cannot be set reliably, probably with metadata, but that is really beyond the scope of Material, I'm sorry!