]> sipb.mit.edu Git - ikiwiki.git/blob - doc/todo/mdwn_preview.mdwn
details
[ikiwiki.git] / doc / todo / mdwn_preview.mdwn
1 The [StackOverflow](http://stackoverflow.com/) site uses markdown for markup.
2 It has a fancy javascript thing for showing a real-time preview of what the user
3 is editing. It would be nice if ikiwiki could support this, too. The thing they
4 use on StackOverflow is supposed to be free software, so it should be easy to
5 add to ikiwiki.
6
7 > See [[wikiwyg]]. Note that I do not have a copy of the code for that, or
8 > it'd be in ikiwiki already. --[[Joey]] 
9
10 >> I just had a brief look at the [[wikiwyg]] page and the link to the plugin was
11 >> broken.  The StackOverflow site uses the [WMD](http://wmd-editor.com/) editor,
12 >> which seems to be related to the [ShowDown](http://attacklab.net/showdown/)
13 >> javascript port of Markdown.  Interestingly, [WMD source](http://wmd.googlecode.com/)
14 >> is now available under an MIT license, though it is supposedly undergoing heavy
15 >> refactoring.  It looks like there was previous discussion ( [[todo/Add_showdown_GUI_input__47__edit]] )
16 >> about a showdown plugin.  Maybe a WMD plugin would be worthwhile.  I might
17 >> look into it if I have time on the weekend. -- [[Will]]
18
19 [[!tag wishlist]]
20
21 >>> Below is a simple plugin/[[patch]] to make use of the WMD editor.  Turns out it isn't hard at all to
22 >>> get a basic version going (which doesn't handle directives at all, nor does it swtich itself off when you're
23 >>> editing something other than Markdown source).  I've
24 >>> removed the done tag so this is visible as a patch. -- [[Will]]
25
26 >>>> Hmm, it would be good if it turned off for !mdwn. Although this could
27 >>>> be difficult for a new page, since there is a dropdown selector to
28 >>>> choose the markup language then. But it should be doable for editing an
29 >>>> existing page.
30
31 >>>>> I agree.  I'm working on this for for both new pages and existing pages.
32 >>>>> It shouldn't be hard once I get WMD going through the javascript API.
33 >>>>> At the moment that is inexplicably failing, and I haven't had time to have a good look at why.
34 >>>>> I may not get a chance to look at this again for a few weeks.
35
36 >>>> Can I get a license statement (ie, GPL-2+) ffrom you for the plugin?
37 >>>> --[[Joey]] 
38
39 >>>>> Certainly.  You're free to use the code I posted below under the GPL-2+ license.  You'll note
40 >>>>> however that I haven't said anything about the WMD code itself.  The WMD web page says:
41
42 >>>>>> "I'm refactoring the code, and will be releasing WMD under the MIT license soon. For now you can download the most recent release (wmd-1.0.1.zip) and use it freely."
43
44 >>>>> It might be best to contact <support@attacklab.net> to for an explicit license on that if you want to include it.
45 >>>>> -- [[Will]]
46
47 ------
48
49 ### Instructions:
50
51
52 Download the [WMD source](http://wmd-editor.com/downloads/wmd-1.0.1.zip).  In that zip file you'll
53 find a few example html files, a readme and `wmd` directory.  Move the `wmd` directory into the
54 ikiwiki `underlays` directory.  You should now have an `underlays/wmd/wmd.js` file as well as 
55 some other javascript files and an images directory in the same place.
56
57 > So, I wonder if I should add a copy of the WMD source to ikiwiki, or rely
58 > on the user or distribution providing it. It does not seem to be packaged
59 > for Debian yet. --[[Joey]] 
60
61 >> This is a good question.  My thought is that it will probably not be packaged any time soon,
62 >> so you're better off adding it to IkiWiki.  I'd contact the author of WMD and ask them.  They
63 >> may have more insight.  -- [[Will]]
64
65 Note that the WMD plugin does **not** handle directives.  For this reason the normal `preview` button
66 remains.  Some CSS to clean up the display of the live WMD preview would be good.
67
68 > Can you elucidate the CSS comment -- or will it be obvious what you mean
69 > when I try it? Is it what's needed for the live preview? --[[Joey]]
70
71 >> In the version of the plugin below, a new `div` is added just below the form.  WMD
72 >> populates this div with the HTML it generates from the Markdown source.  This is not very
73 >> pretty at the moment - it appears in the same place as the preview used to, but with no
74 >> header or anything.  Any standard IkiWiki preview will appear below the WMD live preview.
75 >> I recommend having a look at <http://wmd-editor.com/examples/splitscreen>
76 >> for what a little CSS could achieve.  -- [[Will]]
77
78 Install the following patch and plugin file.  Then enable the 'wmd' plugin.
79
80
81     diff --git a/templates/editpage.tmpl b/templates/editpage.tmpl
82     index 4b54db2..b1cf015 100644
83     --- a/templates/editpage.tmpl
84     +++ b/templates/editpage.tmpl
85     @@ -37,6 +37,7 @@ Optional comment about this change:<br />
86      </div>
87      </TMPL_IF>
88      <TMPL_VAR FORM-END>
89     +<TMPL_VAR WMD_PREVIEW>
90      
91      <TMPL_IF NAME="PAGE_PREVIEW">
92      <hr />
93
94 -----
95
96     #!/usr/bin/perl
97     package IkiWiki::Plugin::wmd;
98     
99     use warnings;
100     use strict;
101     use IkiWiki 3.00;
102     use POSIX;
103     use Encode;
104     
105     sub import {
106         add_underlay("wmd");
107         hook(type => "getsetup", id => "wmd", call => \&getsetup);
108         hook(type => "formbuilder_setup", id => "wmd", call => \&formbuilder_setup);
109     }
110     
111     sub getsetup () {
112         return
113                 plugin => {
114                         safe => 1,
115                         rebuild => 1,
116                 },
117     }
118     
119     sub formbuilder_setup (@) {
120         my %params=@_;
121         my $form=$params{form};
122     
123         return if ! defined $form->field("do");
124         
125         return unless (($form->field("do") eq "edit") ||
126                                 ($form->field("do") eq "create"));
127     
128         $form->tmpl_param("wmd_preview", "<div class=\"wmd-preview\"></div>\n".include_javascript(undef, 1));
129     }
130     
131     sub include_javascript ($;$) {
132         my $page=shift;
133         my $absolute=shift;
134         
135         return '<script src="'.urlto("wmd.js", $page, $absolute).
136                 '" type="text/javascript"></script>'."\n";
137     }
138     
139     1
140