Opened 3 months ago

Last modified 3 months ago

#34437 assigned task

migrate help.tpo into a gitlab wiki

Reported by: anarcat Owned by: anarcat
Priority: Low Milestone:
Component: Internal Services/Tor Sysadmin Team Version:
Severity: Minor Keywords: tpa-roadmap-june
Cc: Actual Points:
Parent ID: Points:
Reviewer: Sponsor:

Description (last modified by anarcat)

we are currently using ikiwiki to host our documentation. that has served us well so far: it's available as a static site in the static mirror system and allows all sysadmins to have a static, offsite copy of the documentation when everything is down.

but ikiwiki is showing its age. it's an old program written in Perl, difficult to theme and not very welcoming to new users. for example, it's impossible for a user unfamiliar with git to contribute to the documentation. it also has its own unique Markdown dialect that is not used anywhere else. and while Markdown itself is not standardized and has lots of such dialects, there is /some/ convergence around CommonMark and GFM (GitHub's markdown) as de-facto standards at least, which ikiwiki still has to catchup with. it also has powerful macros which are nice to make complex websites, but do not render in the offline documentation, making us dependent on the rendered copy (as opposed to setting up client-side tools to peruse the documentation).

gitlab wikis, in contrast, have a web interface to edit pages. it doesn't have the macros ikiwiki has, but that's nothing a few commandline hacks can't fix... or at least we should consider it. they don't have macros or any more powerful features that ikiwiki has, but maybe that's exactly what we want.

this is not blocking the trac to gitlab migration, but it would be nice to jump onboard with everyone, since we will be migrating the Trac wiki onto gitlab as well...

Child Tickets

Change History (5)

comment:1 Changed 3 months ago by anarcat

Here are the ikiwik macros in use in the wiki:

$ git grep -h '\[\[!' | sed 's/ .*//' | sort | uniq -c | sort -n 
      1 [[!toc]]
     10 [[!map
     24 [[!meta
     45 [[!toc
  • [[!toc can be converted to [[_TOC_]]. this is a non-standard "GFM" (GitHub Formatted Markdown) extension
  • [[!meta should be converted to a front matter block, since it's all titles (the meta directive supports other uses but we don't use those). this is a non-standard "GFM" extension
  • [[!map has no good equivalent in markdown, but could be replaced by the page listings built into the gitlab wiki, on the right column

I will also note that [[links|like this]] would need to be converted as well. those are tricky because they need to take into account context of the refering page. we have about 184 such links to cover.

I have written code to convert from ikiwiki's peculiar dialect into a more standard (in my case Hugo's) Markdown dialect here:

that code can probably be reused here, although it only handles the "meta" case for now. see also the associated notes here:

this sounds like a lot of work, but I will note that the longer we wait to make this transition, the harder this will be to do correctly, so the sooner the better.

Last edited 3 months ago by anarcat (previous) (diff)

comment:2 Changed 3 months ago by anarcat

Keywords: tpa-roadmap-june added

comment:3 Changed 3 months ago by anarcat

Description: modified (diff)

comment:4 Changed 3 months ago by anarcat

this was made part of a larger TPA-RFC-5:

comment:5 Changed 3 months ago by anarcat

Component: Internal Services/Service - tracInternal Services/Tor Sysadmin Team
Owner: changed from qbi to anarcat
Status: newassigned

i definitely did not mean to assign that to qbi :)

Note: See TracTickets for help on using tickets.