Ikiwiki
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 python-docutils
Setup [1]
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 [2]
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
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).
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:
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!
===
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.
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