ikiwiki

Will Thompson

2007-11-22

Background

Do you like websites?
Apparently people do.
Apparently compsoc has one.
- (modulo regular server death)

We had a website...

Screenshot of the old website

... Andrew didn't approve

(Please imagine that there is a humorous photograph of Andrew here, with the words “DO NOT WANT” badly added to the bottom in Impact.)
He carelessly has no photographs on his Farcebook profile.
The rest of the committee carelessly have no humorous photographs of him.
Loss.

Andrew vs. the logo

the old Compsoc logo

notice the complete lack of drop shadow.
it also doesn't use the One True Font™

One true font

...aaaaanyway.

Adding an event (old-style)

% vi events/termcards/tt2007/wk2.shtml
    <table class="termcard" summary="Layout for event information">
    <tr>
        <th class="eh" colspan="2"> Second Life and IBM </th>
    </tr>
    <tr>
        <td class="ei"> Wednesday 2nd May,<br/> 20:30 </td>
        <td class="ei">
            Morley Fletcher Room, Worcester College <br /><a
            href="http://maps.google.co.uk/maps?f=q&hl=en&q=
            OX1+2HB&layer=&ie=UTF8&z=16&om=1&iwloc=addr">Location
            of Worcester</a> - Meet at Porter's Lodge
        </td>
    </tr>

I don't like writing HTML by hand.

New site requirements

No HTML in ~~site~~ sight.
Editable in a text editor.
Version control.
RSS feeds, etc.

Enter Ikiwiki

Wiki compiler
Pages written in Markdown (or rst or whatever if you don't like mdwn)
Stored in a VCS (svn, git, monotone, mercurial, tla)
Extensible in Perl (~~yay!~~ hrm.)
- Actually, you can also extend it in any language that can do XMLRPC.
70-odd plugins (site map, orphan-finding, typography, tag cloud, ...)

Get started

Following http://ikiwiki.info/setup/:

% sudo apt-get install ikiwiki apache2
% SRCDIR=/home/share/wiki/wc
% DESTDIR=/home/share/wiki/html
  ... map some URL to $DESTDIR ...
% mkdir $SRCDIR; cd $SRCDIR
% cat > index.mdwn
I like [lolcats][] and [ikiwiki][].

---

We has a [[sandbox]]!

[lolcats]: http://linkpot.net/strangles/
[ikiwiki]: http://ikiwiki.info

Compile it...

% ikiwiki --verbose $SRCDIR $DESTDIR \
  --url=http://holly.lan/wiki/ \
  --wikiname='High-Tech Wiki'

woo look a wiki

Add a setup file

% cp /usr/share/doc/ikiwiki/html/ikiwiki.setup .ikiwiki/
% vim .ikiwiki/ikiwiki.setup
  ...clackity clackity...
% ikiwiki --setup .ikiwiki/ikiwiki.setup

Set up a CGI wrapper in ikiwiki.setup to allow editing through a browser (in case you don't like vim)
The Compsoc website doesn't do this...
...but I'm using the wiki illustrated here for my housemates, and I think they'd rather use the browser. :(

Web editing

editing

Version control

No darcs support. :'(
I don't like subversion.
Upstream recommends git, but git is insane.
Mercurial is supported, but I can't figure out how to add commit hooks.
TLA? No thanks.
Monotone? No thanks.
Okay, I'll use svn.
- Compsoc one uses svn too.

Create a SVN repo

% REPO=/home/share/wiki/repo
% svnadmin create $REPO
% svn mkdir file://$REPO/trunk -m "create trunk"
% cd $SRCDIR
% svn co file://$REPO/trunk .
% svn add *
% svn commit -m "initial import"
% vim .ikiwiki/ikiwiki.setup
  ... configure svn repo ...
% this is quite boring
% lalala
% why are you reading this?
% you should be listening to me !!!

AND THEN

Now you can check out the repo on your local machine:

% svn co svn+ssh://holly.lan/home/share/wiki/repo/trunk wiki
% cd wiki
 ... edit stuff ...
% svn ci -m "this is a helpful commit message"

and the wiki is magically updated!

Web edits get committed too.
You can set up an in-browser history viewer.

Cool things

Instant ~~blog~~ blag:

% cat > blag.mdwn
[[inline pages="blag/*" show="10" postform="yes"]]
% mkdir blag
% vim blag/hello.mdwn
% svn add blag.mdwn blag blag/*; svn ci -m 'lalala'

We use a variant on this for termcards.

Cool things

blag screenshot

Compsoc-specific

Wrote a plugin for termcards and events and stuff:

% cat termcards/2007/michaelmas/Week 7/Lightning Talks.mdwn
[[event venue="Morley Fletcher Room, Worcester"
    date="2007-11-22 20:00"]]

One room, one projector, and many speakers. Everyone is
invited to give a short talk on something they're
involved in or interested in; don't worry ...
% cat termcards/2007/michaelmas.mdwn
[[term ]]

No more editing HTML tables!

Termcard

termcard

Compsoccy hiccups

You have to make a whole tree of stub year, term, week pages
but computers can “automate” things apparently?

Badness

HTML::Template sucks!

<TMPL_LOOP NAME="TAGS">
    <TMPL_VAR NAME=LINK>
</TMPL_LOOP>

Give me Template Toolkit any day!

[% for tag in tags %]
    [% tag.link %]
[% end %]

Also notice: Iki is generating HTML and stuffing it in a variable!

More Badness

Default skin sucks. (But it's open source! I could send a patch!)
Because it's a compiler, dynamically generated pages are hard.
- We have some hacks for the machine status page.
- In general, if you have a page that should change daily, you set up a cronjob.
- Someone remind me to set that up for the front page.
URLs are case-sensitive.

I'm done now.

Questions?

Coda: linkpot.net/strangles

Wikipedia lolcat

Markdown Digression

Markdown is great.

### this becomes an h3

You can do *italics* and **underline**.

* bulleted list
     - nested lists

1. numbered lists
3. although it ignores numbers other than the first

> email-style quoting makes a blockquote

I actually wrote this presentation in Markdown!

Markdown Digression

this becomes an h3

You can do italics and underline.

bulleted list
- nested lists
numbered lists
although it ignores numbers other than the first

email-style quoting makes a blockquote

Pandoc Digression

Alternative Markdown processor
Can convert from: markdown, rst, html, latex
Can convert to: html, s5, docbook, latex, context, man, markdown, rst, rtf
s5 is a javascripty presentation thing that Eric Mayer wrote. You should use it too.
For bonus points, it's written in Haskell!

Pandoc's Markdown

Pandoc supports some extensions to standard Markdown:

~~Strikeout~~  Let's have a footnote[^1].

Term
:    Definition of term.

Inline L~A~T^E^X: $ \alpha \Rarrow \beta $

[^1]: blah blah blah

It also does tables, but why would you do that?!