How does the Markdown plugin work?

[eudicots]

How does the Markdown plugin work?

[dalanmiller]

Eventually answered my own question. But it is rather confusing, I'm going to submit a pull request to add documentation on using Markdown as well as using Markdown in conjunction with the blog plugin!

[koenbok]

Ha I understand how that could be confusing. Originally I though I would need a plugin for it, but later on I settled on just using django template tags. You can see an example that works well here: https://github.com/koenbok/CactusBlog

I should probably remove the markdown plugin.

[koenbok]

Pull requests always welcome!

[pjv]

i think i see how you mean for this to work. maybe this was the original idea for using a markdown plugin, but wouldn't it be nicer (especially if one were building a blog framework to be used by less dev-oriented folks) to be able to just throw a directory full of strictly markdown *.md files at the blog plugin and have it do the right thing without the files having to include a bunch of django template markup?

i guess somehow the idea of having template markup mixed into the content (e.g. your example blog posts) is bugging me.

[koenbok]

If we can solve these things nicely I'd be fine with that:

1. The md file needs to know what template to use (and what block to override), it should be easy to discover/grasp
2. A way to predict the output filename for linking (likely just as simple as .md -> .html)
3. A nice way to mix in context variables

[pjv]

i guess i think that the the md file shouldn't need to know anything except its content (and i include in that its meta content like title, author, date, maybe "tags", etc).

maybe i am missing the logic here (sorry if i am), but couldn't those three things you mentioned be managed for a given blog instance by a config file for the blog plugin?

[amitu]

Even I prefer the simplicity of jekyll when dealing with .md files. Consider this page for example:

title: My first post
author: Koen Bok
date: 22-07-2012

{% extends "post.html" %}
{% block body %}

{% load markup %}
{% filter markdown %}

#### markdown content

[link](http://google.com)

{% endfilter %}
{% endblock %}

This can as easily be represented by

title: My first post
author: Koen Bok
date: 22-07-2012
base: post.html

#### markdown content

[link](http://google.com)

And a markdown plugin may take care of generating the above page based on this.

It would not still be exactly what @pjv suggested, "to be able to just throw a directory full of strictly markdown *.md files at the blog plugin", we will have to add the header in each .md file, but probably this is a fair tradeoff.

How does it sound?

[koenbok]

This is basically what I tried to accomplish with my markdown plugin. So maybe we should add it again, finish it and enable it by default. Then we can basically use whatever we prefer (I think there are still valid reasons doing it like I did in the blog, when you want to mix markdown and html, for example).

One thing that we might need to do something smart for is when someone makes a markdown file without providing a base template and/or override block in the header. Maybe a warning in the console will suffice, but maybe there is something smarter.

I'm busy for the next few days, so if anyone is up to write it that would be awesome. If not I'll look into it next week or so.

[pjv]

@amitu : that is exactly what i had in mind when i said to throw a directory full of *.md at the blog plugin. i definitely meant *.md files including meta-data (which is still markdown if you include the markdown metadata extension).

@koenbok : i thought that's what you might have been going after with the markdown plugin originally.

i have contributed to (and am currently using for some projects) another python-based static blog generator which lives here on github called cytoplasm. i'm looking to migrate to cactus because cytoplasm is no longer under active development by the original author and i don't have time to take it on properly. anyway, cytoplasm, which by default uses mako (but can potentially handle other templating systems via plugins) instead of django for templating, uses a config file to manage things like which base template / block to use. in this way, you set up a mode of generating a blog for a particular site - not on a post-by-post basis, which is obviously more restrictive, but also simpler and probably covers 99% of how people are likely to want to create a blog, i think. maybe having a default by config file which is over-rideable with markdown metadata would be the way to go?

there are some other things that cytoplasm does that i like that i would definitely try to work into the cactus blog plugin as i have time. the main one being how it can create a date-based hierarchy of output folders that translate directly into nice URL's like myblog.com/2012/05/26/bla-bla-bla.html. based on the date in the markdown files metadata, during the build phase it will generate the directories: 2012, 05, 26 and populate with the posts (named with their title-slug).

[amitu]

Config

I believe this is a must have. I like the jekyll style _config.yaml. The content of this file to be read and available as site.config. Other option is to rely on django's configuration system and pass the _config.yaml to django in Site.setup() call to settings.configure. This second option allows us to do much more than what is possible, adding all kinds of django settings becomes possible.

In interest of backward compatibility we should not require _config.yaml, if its there include it, else continue to do what we currently do in site.setup().

Markdown meta-data vs YAML Front Matter

I am moving away from jekyll to cactus primarily because I prefer restructuredtext over markdown. I much like YAML Front Matter as in jekyll. Adopting this also gives us easier migration from jekyll.

Support for .md/.rst/.etc

I feel there should be no restrictions on this, there are loads of different formats/markups these days and everybody has a favorite. My suggestion then is that each file be handled by a separate plugin.

Sequential plugin application

If we handle .md file through a plugin, and we have another plugin for blog, then "date-based hierarchy of output folders" requires multiple plugins will be applied and some plugin will change the file extension, and some other plugin will change the path. I am not sure if the current plugin system handles this.

One suggestion is we start with site.pages(), this contains all files in pages folder read at the beginning of the build, but then onwards plugins can add or remove items in it, so markdown plugin will find all files ending with .md, convert it to .html, stores the file in same place as .md file, remove .md file reference from site.pages, and add .html file to a cleanup list, files that would be deleted at the end of the build, and then blog plugin goes through pages list, .html files and based on metadata translates the path to data based path by creating the requisite folders, and adds the new files and folders to cleanup location.

Cleanup portion sounds a bit complicated, we may have a staging folder, where intermediary output may be copied and nuked after build.

[mduggins]

I am new to python and cactus, could someone please let me know how to correct this problem:
DeprecationWarning: The markdown filter has been deprecated category=DeprecationWarning

Thanks for any help you can provide me!