An extension to python markdown that takes metadata embedded as YAML in a page of markdown and render it as JSON-LD in the HTML created by MkDocs. The extracted metadata is also returned as a python dict in the markdown object.

Currently development is focussed on the needs of the K12-OCX project for curriculum content materials (learning resources).

Test metadata

YAML input

"@context": "http://schema.org"
"@id": "#lesson1"
"@type":
    - CreativeWork
learningResourceType: LessonPlan
hasPart: {
  "@id": "#activity1"
}
author:
    "@type": Person
    name: Phil Barker

Default JSON-LD output

<script type="application/ld+json">
{ "@context":  "http://schema.org",
  "@id": "#lesson1",
  "@type":["CreativeWork"],
  "learningResourceType": "LessonPlan",
  "name": "Practice Counting Strategies",
  "hasPart": {
    "@id": "#activity1-1"
  }
  "author": {
    "@type": "Person"
    "name": "Phil Barker"
  }
}
</script>

Optionally the context string can be omitted and specified as an option when calling the extension (useful if you have a complex context and several blocks of metadata).

See test.py for fully working examples embedded in markdown.

Requirements & dependencies

Python 3 (tested on Python 3.6.7)

Designed for use with MkDocs

Uses python packages Python-Markdown, PyYAML and json.

Installation with setup.py requires setuptools

Doesn't play nicely with other python markdown extensions that use --- to delineate YAML (or anything else), notably the meta extension.

Installation

(Warning: exercise caution this early release software with no warranty, test this first in a virtual environment!)

(venv)$ git clone https://github.com/philbarker/ocxmd.git
(venv)$ cd ocxmd
(venv)$ pytest test.py
(venv)$ python setup.py [test|develop|install]

Usage in MkDocs

Add ocxmd to your extensions block in mkdocs.yml:

markdown_extensions:
  - ocxmd:
     context: '"@context": "http://schema.org"'

The context string can be changed to whatever you want.

You may have to restart MkDocs for this to take.

Usage in Python scripts

import markdown
from ocxmd import OCXMetadata
TESTINPUT = '''
#YAML to JSON-LD test
---
"@id": "#Lesson1"
name: "Test Lesson 1"
---
I started with some YAML and turned it into JSON-LD
'''
md = markdown.Markdown(
    extensions=["ocxmd"],
    extension_configs={"ocxmd": {"context": "'@context' : 'http://schema.org'"}},
)
print( md.convert(TESTINPUT) )
print( md.meta )

YAML in Markdown

The YAML must be separated from the rest of the markdown text by --- before and after.

Because YAML expects the first character of a key or value to be alphanumeric it is safest to quote any keys or values required by JSON-LD to begin with @ or # etc.

#YAML to JSON-LD test
---
"@context": "http://schema.org"
"@id": "#Lesson1"
name: "Test Lesson 1"
"@type":
    - CreativeWork
learningResourceType: LessonPlan
hasPart: {
  "@id": "#activity1"
}
author:
    "@type": Person
    name: Fred Blogs
---

I started with some YAML and turned it into JSON-LD

Here is some more YAML
---
"@context": "http://schema.org"
"@id": "#activity1"
"@type":
    - CreativeWork
name: "Test Activity 1.1"
learningResourceType: Activity
---

All going well you will have to view source or inspect the HTML to see the output.

Acknowledgements

I was helped in writing this by reference to Nikita Sivakov's full-yaml-metadata extension