Pass Context to Converter Plugins #1509

Closed
PeteMichaud opened this Issue Sep 6, 2013 · 4 comments

2 participants

@PeteMichaud

I would like to build a wiki linking system. Basically I want to include this in my post and page markup:

[[My Page Title]]

And it will be converted into:

<a href="url/to/my-page-title.html">My Page Title</a>

A new liquid tag just isn't going to do it. Syntax like {% wiki My Page Tile %} not only isn't standard wiki format, but it would be awful to use. I want the [[]] syntax.

This seems like an ideal job for a converter: just gsub any "[[string]]" with the the anchor markup during the conversion.

The problem is that, as far as I can tell, Converters don't have access to the site object or the pages collection, and I think it's by design. Every other plugin gets a site object or at a least context from which you can retrieve the site object, but Converters don't. I guess the theory is that Converters should be able to work regardless of context.

But I think this use case is legit -- I need the collection of pages to compare the given title against so I can get the right permalink to inject into the anchor.

Tags and filters won't work, I don't think I can use a generator for this--I think a converter is the right type of plugin to use here, but I need the context in order to do my conversion.

We can pass it as a second argument, so it doesn't affect any existing plugins, but new ones that want to use the context have access to it. Doable?

@parkr
Jekyll member

It's definitely doable but I don't think modifying converters is the right place to do it. This kind of conversion isn't like Markdown or Textile, but more like Liquid. You'll notice in convertible.rb that Liquid has its very own method and does not behave like a normal converter. I think the original discussion around adding other converters made it such that other Markdown/Textile-like converters were easy to implement and could change, but that we had to stick with Liquid. I almost think we need another kind of plugin, maybe called a Renderer. This would be something that could replace Liquid in a given site. It would get access to context (all the info enshrined in page, site and jekyll Liquid variables) and be processed prior to all conversion by normal Converters.

What do you think about that?

@PeteMichaud

I think it's a great idea, but I'd not call them Renderers, because I think it's confusing for a newcomer to understand that a Renderer transforms the content of a file, while a Converter renders the final file.

We could call them Transformers, but actually I think that limits them conceptually. Really we're getting a context and some raw content, and "doing stuff" then returning some other content. We're imagining that "doing stuff" involves transforming the content, but we might be doing anything -- logging the number of keywords to a database, for example. So really we're talking about Processors.

But I could see an argument that anything a "processor" could do that didn't involve transformation should really belong in a generator... I'm on the fence. If we want a more focused type of plugin, Transformer is a good name. If we want a more general purpose plugin, Processor would work.

@PeteMichaud

I wrote a bonehead version of the wiki plugin as a sort of test implementation to imagine how a transformer might work:

https://github.com/PeteMichaud/jekyllpedia/blob/master/_plugins/jekyllpedia.rb

I pass the content and context into the transform method, but another alternative is to pass the context when we initialize the plugin object. That would mean that a plugin author has to persist the context herself if she wants to. Then transform would just take the content argument.

Edit: I kind of talked myself into the second option. This way the method signatures are squeaky clean, and the match method can access the context as well.

@parkr
Jekyll member

haha, your avatar is great.

With multiple converters ( #2666 ), you could come up with something that would convert these. Or use a generator which gets the whole site. The world is your oyster!

@parkr parkr closed this Jul 31, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment