marcuskammer/coleslaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
coleslaw/docs/plugin-api.md
Brit Butler e44d0bde9e Make add-injection support more complex injections. Thanks @PuercoPop. 
In short, an injection is now a FUNCTION that takes a
document and returns either a STRING to insert in the
page (possibly with data from the document) or NIL.
2014-09-22 14:31:08 -04:00

2.8 KiB
Raw Blame History

General Use

  1. A lisp file should be created in coleslaw's plugins directory.

  2. Any necessary lisp libraries not loaded by coleslaw should be included like so:

    (eval-when (:compile-toplevel :load-toplevel) (ql:quickload '(foo bar)))

  3. A package should be created for the plugin code like so:

    (defpackage :coleslaw-$NAME (:use :cl) (:export #:enable) ...)

    where $NAME is the pathname-name of the lisp file. (eg. :coleslaw-disqus for disqus.lisp)

  4. An enable function should be present even if it's a no-op. Any work to enable the plugin is done there.

Extension Points

  • New functionality via JS, for example the Disqus and Mathjax plugins. In this case, the plugin's enable function should call add-injection with an injection and a keyword. The injection is a function that takes a Document and returns a string to insert in the page or nil. The keyword specifies whether the injected text goes in the HEAD or BODY element. The Disqus plugin is a good example of this.

  • New markup formats, for example the ReStructuredText plugin, can be created by definining an appropriate render-text method. The method takes text and format arguments and is EQL-specialized on the format. Format should be a keyword matching the file extension (or pathname-type) of the markup format. (eg. :rst for ReStructuredText)

  • New hosting options, for example the Amazon S3 plugin, can be created by definining a deploy :after method. The method takes a staging directory, likely uninteresting in the :after stage. But by importing *config* from the coleslaw package and getting its deploy location with (deploy-dir *config*) a number of interesting options become possible.

  • New content types, for example the static page content type, can be created by definining a subclass of CONTENT along with a template, and render, page-url, and publish methods. The PAGE content type cheats a bit by reusing the existing POST template.

  • New service integrations, for example crossposting to twitter/facebook/tumblr/livejournal/etc, is also possible by adding an :after hook to the deploy method. The hook can iterate over the results of the get-updated-files to crosspost any new content. The Twitter plugin is a good example of this.