Hoping for ability to import/sync Markdown (.md) from GitHub into new/existing courses

Hoping there is a way to create course module content (HTML it appears) from raw GitHub markdown maintained in an open source repo. We can currently create GitBooks and similar HTML content and allow our community to maintain the raw markdown source together as features are added or change over time. Is such a function possible? Initially, just import of .md to .html would be extremely helpful and then hoping for a future “sync” we could run and pull (rebuild html) from the github source repo. Any help in this direction would be appreciated and likely save weeks of effort creating several courses initially and simplify long term maint. which can be spread to the contribs/committers on our open source project…

Hi @mrutkowski,

What you are saying it possible if you create a script that converts the current markdown structure into a course structure that can be imported into the platform.

You create a script in the language of your choice that:

  • reads the current gitbook/markdown structure and extracts a course structure out of it with sections, subsections, units and content blocks.
  • Each block of HTML content can be put in an HTML block.
  • The HTML content can be rendered using a markdown-to-html library
  • Internal links can be modified to follow the URL structure of edx-platform.

Note that the internal link modification could be implemented as a plugin to the markdown converter. Python-Markdown for instance supports such plugins. GitBook itself might support the creation of plugins that simplify this, I am not familiar with it but it does seem to support plugins.

This is likely to take a bit of effort but will eventually allow automating the GitBook/markdown to course conversion process. You can read more about course imports/exports here and can see a sample XML importable demo course here.

Hi @mrutkowski @xitij2000, I’m curious to hear if you’ve implemented such a GitBook/markdown to course converter? it sounds like this approach could speed up course authoring in some cases and also provide versioning of the course content. Thanks!

We (OpenCraft) have not created any such script, but would be happy to help with that.

For versioning of course content, it is possible to store the course structure in git, as you can see here for the demo course by edX: https://github.com/edx/edx-demo-course/

You can also modify the course structure in studio, and export it after modification to keep a history.

Thanks for your reply @xitij2000!

This is also something that would be extremely valuable to me and our team - we are very used to using Git / Github for collaboration - and having to do editing and review in the GUI will make things much harder.

I wonder whether it’s worth gathering a set of people who interested in this feature, to see what we can do?

Same here. I agree, integrating with GIT would be the perfect move. I can imagine two different situations:

  • Edit a course in edX and the changes are pushed to GIT
  • Make a change in GIT and after the commit it updates the course on the edX server

I don’t know if this is what you are looking for, but there used to be something from MIT that might fit what you are looking for?

Maybe @pdpinch or someone else from MIT can tell you more about it?

1 Like

In a previous incarnation I helped create olx-utils, and one of the design goals was precisely to allow creating course content in markdown and storing the source in git. It also makes reusing blocks possible via templates. And IIRC, it’s also possible to push the course directly into an Open edX instance from the command line.

1 Like