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/articleog:type
- The type of content (e.g., website, article, book)og:image
- The URL of an image to represent your contentog:url
- The canonical URL of your pageog:description
- A brief description of your contentog:site_name
- The name of your overall site
Default Social Usage
You can just add the social plugin
1 2 |
|
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:
- Create a directory called
overrides
in your project root - 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 |
|
- Update your
mkdocs.yml
to use your custom template:
1 2 3 |
|
Page-specific Metadata
For page-specific descriptions, you can add front matter to each markdown file:
1 2 3 4 5 6 |
|
Best Practices for Open Graph Tags
- Image Dimensions: Use images that are at least 1200×630 pixels for optimal display
- Description Length: Keep descriptions between 70-200 characters
- Unique Images: Create unique images for important pages
- 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 |
|
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 |
|
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?