1. We are using ikiwiki
    1. Build the wiki locally (before committing changes)
    2. Ikiwiki tips

We are using ikiwiki

That way we build an online readable doc website at https://internal.squat.net. That means we must respect Ikiwiki formatting. The full Ikiwiki documentation is really helpful.

Build the wiki locally (before committing changes)

  1. Clone the git repo
    • git clone root@skwotfarm.squat.net:./repos/internal-ikiwiki
  2. Copy ikiwiki.setup somewhere out of your local git clone
  3. Edit ikiwiki.setup to change some values:
    • srcdir: must point to the git repo (it's where ikiwiki will look to find files to compile)
    • destdir: where the compiled wiki files must be put.
    • url: you can use "http://localhost/bla" or "file:///tmp/bla" depending on how you want to access your wiki localy
    • cgiurl: how the cgi will be accessed from the web browser
    • cgi_wrapper: where generated ikiwiki cgi has to be put. If you're not using a webserver to browse your local wiki, don't mind changing this.
    • libdir: where is your local ikiwiki library (usually /home/<user>/.ikiwiki)
    • cookiejar
    • git_wrapper: the git post-update hook that ikiwiki builds to automatically rebuild after a commit or a push. Comment it out!
  4. Build
    • ikiwiki --setup /path/to/your/local/ikiwiki.setup --verbose --no-rcs
    • (--no-rcs is here to prevent ikiwiki to fetch and push to the remote git… and it's quite faster than without!)
  5. Browse
  6. Edit files
  7. Refresh
    • ikiwiki --setup /path/to/your/local/ikiwiki.setup --verbose --no-rcs --refresh
    • Or ikiwiki --refresh /path/to/srcdir /path/to/dstdir

NOTE: Remember to not push your local changes to ikiwiki.setup as it might break the live Ikiwiki

Ikiwiki tips

  • The docs are here
  • Inline code-style text is done by putting your text between backticks: `my code`.
  • Formatting: https://ikiwiki.info/ikiwiki/subpage/linkingrules/
  • There are two types of links: external and internal
    • External links use one of these syntaxes:
      • [link name](link_url)
      • <https://link.to>
    • Internal links:
      • [[page_name]]
      • [[link name|page_name]]
      • Ikiwiki links are case insensitive: [[pAge_NAme]] will render a link to the matching lowercase page. If two pages exist with same filename but a different case, ikiwiki will match to the lowercase one except when the link uses the exact case.
      • Subpages: see https://ikiwiki.info/ikiwiki/subpage/linkingrules/