1. Why
  2. First conversion attempt
  3. Hugo ultra short primer
  4. Results
  5. Inventory
    1. Magic links
  6. Tasks
  7. Other converters


First conversion attempt

I had to rename all files, and move stuff into content/, then things started generally working "working" (as in "breaking").

I had to clone a theme, the quickstart suggest:

git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

Then I had a failure to parse comments:

Error: Error building site: "/home/anarcat/wikis/anarc.at/content/blog/2013-02-04-why-i-dont-pulseaudio.md:2:1": starting HTML comment with no end

Workaround, delete all comments:

505  2019-07-18 17:22:08 grep -l -r -- '<!--' * | grep -e comment  -e '\.md$'  | xargs  sed -i '/<!--/d'

Long term solution might be to convert to shortcodes.

I also tried:

607  2019-07-18 17:11:55 grep -l -r -- '-->$' * | grep -e comment  -e '\.md$'
608  2019-07-18 17:12:15 grep -l -r -- '-->$' * | grep -e comment  -e '\.md$' -0 | xargs -0 sed -i 's/-->$/!-->/'
609  2019-07-18 17:12:23 grep -l -r -- '-->$' * | grep -e comment  -e '\.md$'  | xargs  sed -i 's/-->$/!-->/'

Another failure is when it finds an HTML file with an unquoted href argument (e.g. hardware/phone/htc-one-s/apps.html).

Hugo ultra short primer

Maybe the Emacs mode could be useful.


Result of running hugo build after the renames:

                   | EN   
  Pages            | 734  
  Paginator pages  |  63  
  Non-page files   | 549  
  Static files     |   3  
  Processed images |   0  
  Aliases          |  12  
  Sitemaps         |   1  
  Cleaned          |   0  

Things generally look like crap:


List of directives used in my wiki:

$ git grep -h '\[\[!' | sed 's/\[\[!/\n[[!/g' | grep '\[\[!' | sed 's/ .*//' | sort | uniq -c | sort -n
      1 [[!bibtex2html <span class="error">Erreur: cannot find bestlink for &quot;&#94;&quot;</span>]]
^ false positive, in software/ikiwiki-osm
      1 <a class="toggle" href="#services-wiki-ikiwiki-hugo-conversion.default">more</a>
^ IMPORTANT, need to figure it out
     18 [[!img
^ IMPORTANT, need to figure it out
     22 [[!color
^ services table, rebuild by hand
     26 [[!iki
^ shortcodes?
     50 [[!format
^ IMPORTANT, need to figure it out
     55 [[!shortcut
^ shortcode, false positive (in shortcuts)
     72 [[!wikipedia
^ shortcode
     96 [[!toc
^ IMPORTANT, need to figure it out (see aboev)
    109 [[!debcve
^ shortcode
    115 [[!debbug
^ shortcode
    142 [[!debpkg
^ shortcode
    268 [[!inline
mostly used in frontpage and blog, need to figure out
    335 [[!tag
^ IMPORTANT, need to figure it out
    358 [[!comment
^ IMPORTANT, need to figure it out
   1254 [[!meta
^ IMPORTANT, need to figure it out

There are also a ton of "magic ikiwiki links", called wikilink, which have their own unique logic:

$ git grep -h '\[\[[^!]' | sed 's/\[\[/\n[[/g' | grep '\[\[[^!]' | wc -l 

Those will be difficult to convert as the semantics of internal linking in Markdown is not well defined. Or rather, it's bound to HTML (in general) and ikiwiki goes beyond that. Some research needs to be done to see how other engines handle this and how it compares to the linkingrules.

The peculiarities of wikilinks in ikiwiki:

  1. case-insensitiven (e.g. [[OtherPage]] and [[otherpage]] both work) - implemented

  2. subpage lookups (e.g. [[otherpage]] in foo/subpage will look for foo/subpage/otherpage, foo/otherpage, otherpage, in order; [[foo/subpage]] will find /foo/subpage from bar, instead of the expected bar/foo/subpage in HTML) - implemented

  3. absolute lookups (prefixed with /, e.g. [[/about]] links to https://example.com/foo/about if the wiki is in example.com/foo, and not https://example.com/about as HTML normally would - probably relevant only for wikis in subdirectories) - NOT IMPLEMENTED

  4. userdir lookups ([[anarcat]] links to [[users/anarcat]] if userdir is set to users) in some contexts (namely comments, recentchanges, but not normal content) - NOT IMPLEMENTED

  5. backslash escapes (\[[WikiLink]] is not a link) - implemented by the caller (in LINK_RE)

  6. anchor lookups ([[WikiLink#foo]]) - implemented by the caller (in LINK_RE)

  7. there might be other rules like underscore (_) mapping to spaces and other funky escape mechanisms - NOT IMPLEMENTED, look at IkiWiki::titlepage for those


the gist of it is we need to implement:

structural elements needing more thinking:

will be converted by hand:

Work is ongoing in this conversion script.


Comments are a particular beast that desserves its own section. Here are the solutions I found online:

Prjoect Backend Notes
Commento Go + JS not in Debian, but lots of features
Discourse N/A used by the Discourse founder for his comments
Isso Python + JS drop-in replacement for Disqus, used by researchhut
Mastodon N/A approach taken by JAK, using a Mastodon comment server gateway
Remark42 Go + JS not sure... unusual database format

Feature comparison:

Project Features
Commento markdown, Disqus import, voting, spam detection, sticky comments, thread locking, Akismet, email notifications, Social login (Google, GitHub, GitLab, Twitter), SSO, hosted version, not in debian PostgreSQL backend, 11KB client
Coral SSO via JWT, Social (Google, Facebook, OpenID)/email auth, custom CSS, email notifications, comment count, GDPR compliance, Slack integration
Isso markdown, Disqus import, voting, web or email-based moderation, email notifications, Debian package, rate-limiting, RSS, i18n, sqlite backend, 40KB client
JustComments markdown, Social auth, email notifications, RECAPTCHA, moderation, SEO, hosted version
Remark42 markdown, Disqus import, social auth, moderation, voting, pinning, image uploads, RSS, bolt backend, email/telegram notifications
Talkyard mardown, moderation, voting, Q&A, anonymous comments, chat, hosted version

Discarded alternatives:

Platform Why
Disqus common, proprietary spyware, to be avoided
Facebook comments same, thoguh maybe less common
CMSes (WP, Drupal, etc) I want a static website
JustComments opencore model, no moderation or spam control in free version
Talk/Coral a "new commenting experience" designed for "newsrooms"
Hypothes.is annotation system
Caliopen "not ready for prod", interface for proprietary platforms like Facebook/Twitter
Utterances github issues commenting system
Staticman assumes a GitHub backend
Talkyard Scala? seems way overkill for a simple blog

Other converters

Created . Edited .