Skip to content

The Open Graph Metadata Standard

The Open Graph metadata standards are used by our intelligent textbooks built with mkdocs-material. This section describes how the the metadata in the HTML is used by social media platforms and how we can customize the behavior by using overrides and plugins.

Open Graph Protocol Standards

Open Graph is a protocol that enables any web page to become a rich object in a social graph. Originally created by Facebook in 2010, it's now widely used across many platforms including Twitter, LinkedIn, and Pinterest.

The Open Graph protocol uses meta tags in the HTML <head> section of your website to define how your content should be represented when shared on social media. Here are the core Open Graph tags:

Basic Open Graph Tags

  • og:title - The title of your page/article
  • og:type - The type of content (e.g., website, article, book)
  • og:image - The URL of an image to represent your content
  • og:url - The canonical URL of your page
  • og:description - A brief description of your content
  • og:site_name - The name of your overall site

Default Social Usage

You can just add the social plugin

1
2
plugins:
    - social

Using Overrides in mkdocs-material

If you don't like the default social cards we can build customer ways to used markdown metadata tags to populate and override our default social cards.

Here's how:

  1. Create a directory called overrides in your project root
  2. Create a file overrides/main.html with this content:
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{% extends "base.html" %}

{% block extrahead %}
  <!-- Open Graph / Facebook -->
  <meta property="og:type" content="website">
  <meta property="og:url" content="{{ page.canonical_url }}">
  <meta property="og:title" content="{{ page.title }} - {{ config.site_name }}">
  <meta property="og:description" content="{{ page.meta.description or config.site_description }}">
  <meta property="og:image" content="{{ config.site_url }}img/social-preview.png">

  <!-- Twitter -->
  <meta property="twitter:card" content="summary_large_image">
  <meta property="twitter:url" content="{{ page.canonical_url }}">
  <meta property="twitter:title" content="{{ page.title }} - {{ config.site_name }}">
  <meta property="twitter:description" content="{{ page.meta.description or config.site_description }}">
  <meta property="twitter:image" content="{{ config.site_url }}img/social-preview.png">
{% endblock %}
  1. Update your mkdocs.yml to use your custom template:
1
2
3
theme:
  name: material
  custom_dir: overrides

Page-specific Metadata

For page-specific descriptions, you can add front matter to each markdown file:

1
2
3
4
5
6
---
description: A detailed explanation of how to integrate MicroSims in your intelligent textbook.
image: path-from-your-docs-to-your/custom-image.png
---

# Your Page Title

Best Practices for Open Graph Tags

  1. Image Dimensions: Use images that are at least 1200×630 pixels for optimal display
  2. Description Length: Keep descriptions between 70-200 characters
  3. Unique Images: Create unique images for important pages
  4. Testing: Use the Facebook Sharing Debugger or Twitter Card Validator to test your tags

Example for a MicroSim Page

For a MicroSim page, you might use:

1
2
3
4
5
6
7
---
title: Sine Wave Visualization MicroSim
description: Interactive simulation demonstrating sine wave properties with adjustable frequency and amplitude parameters.
image: /img/sims/sine-wave-preview.png
---

# Sine Wave MicroSim

Note

The metadata block that begins and ends with three dashes MUST be the first lines in the markdown file.

And in your custom template, you'd add:

1
<meta property="og:image" content="{{ page.meta.image or config.site_url }}img/social-preview.png">

This approach ensures your intelligent textbooks and MicroSims will have rich previews when shared on social platforms, increasing engagement with your educational content.

Would you like more specific guidance on implementing this within your existing intelligent textbook framework?