Ikiwiki

made by Barbs

About

Ikiwiki is a very lightweight wiki compiler that generates static html from markdown files through a git repository.

It is a very cool project with terrible documentation, so let's compile what we know and learn in this page!

Installing on Debian

NOTE:

where $WIKI put the name of your wiki

where $USER put the name of the local user

sudo apt install ikiwiki

make sure you also have librpc-xml-perl and python3-docutils

Setup

You run the following command:

ikiwiki --setup /etc/ikiwiki/auto.setup

If you get this error:

/etc/ikiwiki/auto.setup: Only one Term::ReadLine::Gnu instance is allowed. at /usr/share/perl5/IkiWiki/Setup/Automator.pm line 17.

try adding PERL_RL=Perl before ikiwiki

you will then get a series of prompts:

What will the wiki be named? $WIKI
What revision control system to use? git
What wiki user (or openid) will be admin? $USER
Choose a password:

You can later change these settings in /home/$USER/$WIKI.setup

ikiwiki edit flow

Variables

Two important variables in the ikiwiki universe are $srcdir, the source directory, and $destdir, the destination directory.

You make changes in $srcdir only! Ikiwiki does the rest.

by default, your $srcdir is /home/$USER/$WIKI/

and your $destdir is /home/$USER/public_html/$WIKI

Publishing your ikiwiki with nginx

SEE ALSO: Setting up a public server

Ikiwiki on a subdomain

what has worked for me (eleni)

move your $destdir from /home/$USER/public_html/$WIKI in /var/www/html/$WIKI/

DONT FORGET! update /home/$USER/$WIKI.setup with the new destination path!

nginx configuration

inside /etc/nginx/site-available create a new file for your subdomain -> subdomain.example.com

server {

    server_name subdomain.example.com; #YOURSUBDOMAIN

    root /var/www/html/$WIKI;

    index index.html index.htm;

    location / {

        try_files $uri $uri/ =404;

    }

}

then run ln -s /etc/nginx/sites-available/subdomain.example.com /etc/nginx/sites-enabled

restart nginx and you're done!

Installing ikiwiki on a phone server

Claudio pls add here <3

Editing the wiki

Adding content

! always add and modify inside $srcdir !

start by creating an index page with touch index.mdwn then sudo nano index.mdwn to add content. use markdown syntax!

to add the file to the git repository for the first time, run git add index.mdwn

every time you're done make changes to your wiki, run git commit -a -m "your inspirational message" then git push

your last step to compile the files in the git repository in ikiwiki is to run

ikiwiki $srcdir $destdir -- refersh

for example,

ikiwiki /home/$USER/$WIKI/ /home/$USER/public_html/$WIKI --refresh

to create nested linked pages, you can make directories in the $srcdir

Templates

Using global templates

Tou use the default ikiwiki templates found in /usr/share/ikiwiki/templates , you need to create a template folder in /home/$USER/$WIKI/

mkdir templates/

and add a template there. For example, if you want a template for all pages, copy /usr/share/ikiwiki/templates/page.tmpl in /home/$USER/$WIKI/templates and edit to your liking!!

To render a new template in your wiki, you run --rebuild instead of --refresh

Using custom templates

When you make your first index.mdwn in your srcdir, you can then run

ikiwiki --refresh srcdir/ destdir/

You will notice that the wiki header vanishes (goodbyeeee).

First time (before) wiki is created after setup configuration file.

Second time, after refreshing the first time with your .mdwn index file.

SOO together with User:Barbs we kind of got pissed and decided to take a look into what is going on. We started looking into templates, and with no surpise, the main documentation is pretty lame, but we found a link that sort of explains the situation ok:

https://scripts.mit.edu/gitweb/www/ikiwiki.git/blob/b30fed47ea20c4b04c1cf9c68b6d69cfa0612c3a:/doc/wikitemplates.mdwn#l4

Soo, looking back at our index.mdwn, we picked one of the templates listed and added a link in markdown to make use of it we used "blogpost.tmpl":

[[plugins/blogpost.tmpl]]

# Welcome to my ikiwiki

## It sucks

But just for now...

see you soon.

(This is my index.mdwn file)

So this worked (sort of) and it showed the status bar again!

Now the status bar is back, but there is a weird thing at the line where I wrote which template we used.

===

Question for Marloes >:)

Q:Did you define which template to use in your setup file or did you put [[plugins/pagetemplatename]] in every file you made and then rendered it??

Emojis

Because interepreting ikiwiki's official documentation can give you a headache, you can rest your mind by filling your pages with emojis.

https://ikiwiki.info/smileys/

Simply typing the text that is associated with an emoji illustrated at this link, will make it spawn on your page(s) once refreshed

examples:

/!\
{OK}

Customizing the header

blahblah

Customizing CSS

add local.css in the git folder /home/$USER/$WIKI/

that way you can fully customize your wiki!

sometimes, changes in the local.css file is overwritten by the style.css, so if something does not appear to work, try including !important

for example;

body {

max-width:50% !important;

}

Plugins

Some features of ikiwiki are not enabled by default. The documentation mentions that to enable a plugin you can edit your $WIKI.setup file, but there is a command that allows you to activate a plugin without editing the .setup file by hand:

ikiwiki --changesetup $WIKI.setup --plugin calendar

Next you should refresh or rebuild you wiki using the updated setup to see any changes.

Projects built on ikiwiki

• Damaged Earth Catalogue
• Permacomputing
• Fanon Radio Wiki
• Eleni's personal website hehe
• the Everything magazine archive
• David Bremner' personal website (UNB professor)
• Software in the Public Interest

Links to sort

• A table of ikiwiki features
• pmc installation guide