Solution for Using Markdown Content from github?

Question

I like Markdown a lot and I would like to use github to save the content there (also with the added benefit that anybody can submit a PR).

I am not interested in a Markdown editor for Joomla, just an extension that can retrieve Markdown files from github, and transform them in HTML (additionally to cache them for a period).

Similar with what JoomlaTools does.

github => website

Answer 1

As far as I can see the only way to really get the information in a repository is manually, unless you want to look through the commits and all, figuring out what goes where. Though either way it would be best to have a copy of the repo somewhere (auto pull updates and all that, so it would have local files in raw format).

So the best way is to have a cronjob that attempts to pull updates every so often to a specified directory, and use the directory structure for your menu and displaying the files. To parse them the best way is to use your own library but with Joomla you have the JGithub class that can be used like so.

$github = new JGithub;

$result = $github->markdown->render('text here most likely the contents of a file');

echo $result; //will be html

A little warning though that uses the API to render it, so you could run into problems of running into the API limits. You can also use oauth to help bypass it but for such a simple need its best to use a library.

Having the files local in raw format makes it far less of a performance issue to just parse them on the fly as well, so less need for caching as all that is really happening is that you are reading a file anyway, if there is a need to cache it still then, because at this point it would be a customized extension for joomla anyway you could tie into Joomla's caching.

$cache = JCache::getInstance();
//data = rendered output, file is the path (dot separated is best) and extensionName is the custom extension
$cache->store($data,$file,$extensionName);

//then it can be called/checked like this
$cache->get($file,$extensionName);

I mosly just let JModel automatically cache things for me, so my example above may not be entirely correct, but it should be close enough to get somewhere with it.

My examples here are very vague, just a bit of notes on how I would handle this. Kept it simple as I am not 100% sure i totally understand the question, though this should at least help someone :)

Answer 2

Current status: proof of concept, not publicly released.

History

I started working on my own solution, with the temporary name of gitcms. Here is the architecture in a nutshell:

This is how it works:

Github repository

Each time a commit is pushed the repository, and event will be triggered. It is possible to catch this event using a webhook which basically allows to send some meta data in JSON format to an address for further processing.

gitcms

Implemented as a middleware solution, it is not CMS specific. It receives the push event from github, figures out what files changed, fetches the files from github in raw format and converts them to HTML. After the conversion is done, it sends a message to the registered Adapter(s).

Adapter

This is build CMS specific and can interpret the message from the middleware. In the end it needs to create, update and delete articles.

Pending issues

• How to deal with images or any other media files.
• Calls are synchronously, consider decoupling using messages queues.

Answer 3

If it was me, I'd retrieve using whatever method suits you (file_get_contents maybe, I like curl, but whatever) and then use the Parsedown class to turn it into HTML.

http://parsedown.org/

Joomla has its own github class, but I haven't looked to see what it actually does.