Page under construction

We're gathering requirements from the debian-wiki mailing list on this page. Doing so is a big job, and not all discussions have been added here yet.

High-level problems faced while migrating to MediaWiki, with suggested solutions. For general information about the revamp, see DebianWiki/WikiRevamp. For associated scripts and MediaWiki page contents, see the mediawiki-recommendations repo.

Contents

  1. Issues
    1. General conversion issues
    2. Imperative vs. declarative markup
    3. MoinMoin special pages
    4. Talk pages
      1. Recommended solution
      2. Still to do
    5. Access control
      1. Recommended solution
      2. Still to do
      3. See also
    6. Page-wide formatting
      1. Still to do
      2. See also
    7. Language tags
      1. Recommended solution
        1. Arguments for different URL schemes
      2. Fallback solution
      3. Still to do
      4. See also
    8. Table of Contents
      1. Recommended solution
        1. TOC template
    9. #pragma description and #pragma keywords
      1. Recommended solution
      2. See also
    10. #pragma hide-title
      1. Recommended solution
    11. <<Action>>
      1. Recommended solution
    12. <<Date>> and <<DateTime>>
      1. Recommended solution
    13. InterWiki links
      1. Recommended solution
        1. Script to generate InterWiki templates from the old wiki
      2. Still to do
      3. See also
    14. Emoticons
      1. See also
      2. Recommended solution
      3. Fallback solution
    15. Message IDs
      1. Recommended solution
      2. See also
    16. DebianCodename etc.
      1. Recommended solution
        1. Recommended procedure to create Template:DebianInfo
        2. Fallback procedure to create Template:DebianInfo
      2. See also
    17. Admonitions
      1. Still to do
      2. See also
    18. Automatically creating wiki links
      1. Recommended solution
    19. Explicit copyright statements
      1. Recommended solution
      2. See also
    20. <<FullSearch>> and <<FullSearchCached>>
      1. Still to do
      2. See also
    21. Footnotes
      1. Recommended solution
      2. Still to do
      3. See also
  2. Notable pages on the new wiki
    1. DebianHeader
    2. DebianFooter
      1. See also
  3. Recommended extensions
    1. Cargo (not yet decided)
    2. Cite
    3. Emoticons
    4. External Data
    5. Category intersection extensions (not yet decided)
    6. MassEditRegex (not yet decided)
    7. SyntaxHighlight
    8. UniversalLanguageSelector and Translate
    9. WikiSEO or MetaMaster
    10. NoTitle
  4. Ongoing jobs

As of 2025, the Debian wiki uses MoinMoin, but is planning to move to MediaWiki. The two platforms use slightly different formats, so every page will need to be converted. The existing tools don't seem to have been used on a wiki as complex as Debian's, so this will involve some development work on our part.

The most time-consuming part of writing a converter is handling the many little edge cases. A developer who sits down to decide each solution on their own can easily lose momentum from decision fatigue, while a developer who tries to democratise the process can lose momentum from bikeshedding.

This page discusses edge cases, and recommends default solutions for each case. If you disagree with something here, please discuss it on the debian-wiki mailing list, and link to the discussion from this page. Or if you're planning to write a converter, you can be reasonably confident any un-replied-to recommendation isn't an obviously bad idea. That said, these haven't been formally agreed or tested against the full current database, so feel free to do something else if the evidence leads in that direction.

See also the discussion that first lead to this page.

Issues

General conversion issues

Here are some links you will need to read before writing a converter. This page discusses some of the complex cases (like how to migrate tables of contents), but ignores many simple cases (like how to convert comments).

Imperative vs. declarative markup

MediaWiki nudges editors to use more declarative markup than MoinMoin, which creates an awkward choice: do you convert imperative markup in a way that looks clunky, or do you impose your ideas about what the authors were actually trying to say?

Imperative markup specifies low-level rendering actions, declarative markup specifies a high-level goal. To understand the difference, consider the HTML elements <br> and <p>. <br> tells the browser "add a newline between two spans of text" - an imperative statement. <p> tells the browser "treat this span of text however you think paragraphs should be treated" - a declarative statement.

It's impossible to automatically convert imperative to declarative markup in the general case, because they're statements at different levels of abstraction. For example, <br> and <p> are sometimes considered interchangeable, because a paragraph break is usually rendered as a pair of line breaks. But text-to-speech programs need more logic to decide how long to pause at a line break than a paragraph break.

MoinMoin has some built-in declarative markup. For example, the <<FullSearch(text)>> macro tells the wiki "print whichever pages currently contain this text", which can change dynamically when other pages change. But MediaWiki's templates and parser functions let editors create their own markup, and declarative templates have become very common.

When writing a converter, you may want to create MediaWiki templates to implement certain behaviour. When you create such a template, ask yourself whether you are replacing an imperative solution with a declarative one. If so, consider creating a transitional template that precisely replicates the old behaviour, waiting until the migration is complete, then creating a new template and manually rewriting pages that link to the transitional template.

See also the discussion on the mailing list.

MoinMoin special pages

For a list of pages that are recommended not to be migrated directly, see special-pages.json.

Talk pages

The Debian Wiki uses the following mechanisms to indicate talk pages:

MediaWiki has talk pages, such as Talk:MediaWiki or Help_talk:Talk_pages.

  1. if a page contains a line matching #pragma supplementation-page on, ignore that line

  2. convert page names from (.*)/Discussion to Talk:$1

    • user and category pages will need to use User_talk: and Category_talk: respectively

Still to do

Access control

MoinMoin has built-in support for access control lists, MediaWiki has built-in protected pages and an AccessControl extension that begins with a warning about how MediaWiki isn't designed to work this way.

The following pages have denied admin rights for everyone:

The following pages seem to be maintained by the OutreachAdminGroup:

The following pages are marked read-only for user ?FilipusKlutiero. This seems to have happened in the mid-2010's, and the account was renamed to PhilippeCloutier in 2025, so it's not clear whether these are still relevant or likely to work:

The following page is marked read-only for user ?AtlasJobinson:

The following page is marked read-only for user xts:

For details, see Conversion edge cases.

Contact the people involved and agree a solution that works for them.

Still to do

See also

Page-wide formatting

A few pages use the #FORMAT processing instruction to change the format of the entire page. The nearest MediaWiki equivalent is page content models, which look hard to implement.

Still to do

  1. manually convert these to normal {{{ ... }}} blocks before conversion

  2. check they still work
  3. if nobody objects, get rid of this section

See also

Language tags

Note: this feature uses "language" (e.g. English) and "locale" (e.g. England) interchangeably. That hasn't caused a problem in the past, but it may be useful to distinguish them for purposes of migration.

The Debian Wiki uses two mechanisms to indicate language:

MediaWiki uses Extension:UniversalLanguageSelector and Extension:Translate, but (at least in the default configuration) these have a slightly different format and put the language code at the end of the URL, for example pt_BR/FrontPage would become FrontPage/pt-br.

The language tags were reviewed in August 2025, to ensure they were syntactically valid (but not that they actually made sense). Invalid instances may have been added since then.

The <<DebianCodenameLink()>> macro generates language-specific links. Any solution will need to generate similarly language-specific links (e.g. MediaWiki's Special:MyLanguage/<page> URLs resolve to an appropriate page).

Install Extension:UniversalLanguageSelector and Extension:Translate, either configure MediaWiki to use our URLs, or rename pages to use MediaWiki-style URLs.

  1. for pages with a line that matches ^#language ([a-zA-Z][a-zA-Z][-_][a-zA-Z][a-zA-Z]), add |Language=$1 to the {{DebianHeader}}

  2. if any page contains #language but does not match the pattern above, raise an error

Arguments for different URL schemes

Fallback solution

It's possible to make a fairly elegant solution with just MediaWiki templates, without needing to change URL structure.

The full structure of the solution is not included here because it's quite large and hopefully won't be needed, but ExampleForTranslation uses templates that should be usable on the final wiki.

Still to do

See also

Table of Contents

MoinMoin's rules for tables of contents are:

MediaWiki's rules for tables of contents are:

  1. use the TOC template (below)
  2. convert all instances of <<TableOfContents>> to {{TOC}}

  3. convert all instances of <<TableOfContents\((.*?)\)>> to {{TOC|$1}}

  4. for pages that match neither of the previous two patterns, add |TOC=ReviewRequired to the {{DebianHeader}}

  5. if the page contains #pragma section-numbers (0|off), add |SectionNumbers=0 to the {{TOC}} and remove that line

  6. if the page contains #pragma section-numbers ([2-9]), add |min=$1 to the {{TOC}} and remove that line

  7. if the page contains #pragma section-numbers 1, remove that line

  8. if the page contains one of the #pragmas above but not <<TableOfContents>>, raise an error

TOC template

This should be compatible with Mediawiki's template of the same name, but needs to add extra functionality.

For contents, see Template:TOC

The above example does not support align. Consider importing MediaWiki's template as e.g. MWTOC then adapting the above template wrap it.

|min= requires the following CSS to be defined site-wide:

.tocmin-2 vector-toc-level-1,
.tocmin-3 vector-toc-level-1,
.tocmin-3 vector-toc-level-2 {
    display: none;
}

#pragma description and #pragma keywords

MoinMoin supports #pragma description (text) that adds <meta name="description" content="(text)"> to the document's <head> section, and #pragma keywords (text) that adds <meta name="keywords" content="(text)">. The former occurs 555 times on the wiki, the latter 79 times. See device_identifier for a page that includes both.

  1. install WikiSEO or MetaMaster

  2. edit {{DebianHeader}} to use the right syntax for whichever we install

  3. for pages that match #pragma (keywords|description) (.*), add "|".lcfirst($1)."=".$2 to the {{DebianHeader}}

See also

#pragma hide-title

This is used on about 38 pages, including FrontPage and its localisations. We assume this used to hide the title at the top of the page, but it isn't documented and it doesn't actually seem to do anything.

  1. install NoTitle

  2. for pages with a line matching ^#pragma hide-title true$, remove that line and add |Title=ReviewRequired to the {{DebianHeader}}

  3. if this turns out to be unwanted for some reason, edit {{DebianHeader}} to ignore the parameter

<<Action>>

MoinMoin provides an <<Action>> macro that maps to several different MediaWiki features.

  1. find all instances of <<Action\((.*?)\)>>

  2. replace all instances of ',' between brackets with '|'
    • e.g. edit, Edit this section -> edit| Edit this section

  3. replace the whole thing with {{Action|$1}}

For contents, see Template:Action

<<Date>> and <<DateTime>>

MoinMoin provides <<Date>> and <<DateTime>> macros to display dates and times.

Use the #time parser function.

Both MoinMoin and MediaWiki support interwiki links (short URLs for common destinations). The list of interwiki links on the current current wiki is at InterWikiMap, the upcoming wiki uses Special:Interwiki.

This isn't as trivial a conversion as it seems:

  1. automatically convert InterWiki links to templates

  2. add all existing InterWikiMap entries to Special:Interwiki

    • this will catch any conversion errors, and supports users who object to templates
  3. create a template for each prefix (e.g. {{DebianBug}})

    • optionally/later modify some templates to act specially
  4. optionally create a template for each InterWiki link

Script to generate InterWiki templates from the old wiki

generate-interwiki-templates.pl reads the current contents of InterWikiMap, and generates a file pages/Template:$prefix for each $prefix. Each template links to a central InterWiki template, so future maintainers only have to make changes in one place.

Recommended contents:

Still to do

See also

Emoticons

MoinMoin supports smileys by default, MediaWiki has an emoticons extension. The extension's default set is smaller than MoinMoin's, and it's not immediately obvious how to add them.

Note: MoinMoin's emoticon support is case-sensitive. Only the first word in the following {OK} {ok} {oK} series should be converted to an image: {OK} {ok} {oK}

See also

Install the emoticons extension and work out how to add all the smileys.

Fallback solution

Convert smileys to templates with a regular expression like the following:

s/(\(\.\/\)|\:\-\)\)|\{OK\}|\(\!\)|\/\!\\|\:\)\)|\:\-\(|\:\-\)|\:\-\?|\;\-\)|\<\!\>|\<\:\(|\>\:\>|B\-\)|X\-\(|\{\*\}|\{1\}|\{2\}|\{3\}|\{i\}|\{o\}|\{X\}|\|\-\)|\:\(|\:\)|\:\\|\:D|\:o|\;\)|B\)|\|\))/{{Smiley| $1 }}/g;

Import the old smiley files (making sure to deal with the files' copyrights) and/or use the existing files where appropriate. When using the existing files, consider changing or removing the "{width}x{height}px" options in Template:Smiley.

Note: the space around $1 is required, because e.g. {{Smiley:{OK}}} confuses MediaWiki with its trailing }}}.

For contents, see Template:Smiley

Message IDs

Debian's wiki supports <<MessageId(foo-1234@example.com)>> and <<mid(foo-1234@example.com)>>

Convert these macros to templates with a regular expression like the following:

s/<<(?:MessageId|mid)\((.*?)\)>>/{{MessageId|$1}}/g;

Recommended contents:

See also

DebianCodename etc.

Debian's wiki supports <<Debian{Codename,CodenameLink,Date,Version}(suite)>>.

These are implemented as Debian-specific macros that read data from files in /srv/wiki.debian.org/var/apt, and DebianCodenameLink.py generates language-specific links. Those files are in turn generated by the get-debian-suite-info script, which is called daily by a cron job.

Convert these macros to templates with a regular expression like the following:

s/<<Debian(Codename|CodenameLink|Date|Version)\((.*?)\)>>/{{Debian$1|$2}}/g;

Note 1: the templates below all link to a main "DebianInfo" template, making it easier to ensure everything stays in sync. Advanced users may also want to call it directly in some cases.

Note 2: The recommended "DebianCodenameLink" template automatically linkifies the text (like <<DebianCodenameLink>> does), whereas "DebianInfo" returns plain text. Again, this might be useful for some advanced users.

Recommended contents:

Fallback procedure to create Template:DebianInfo

Write a bot that automatically updates Template:DebianInfo. For reference, the remainder of this page calls the MoinMoin macros and generates the relevant text. To demonstrate the fallback solution, copy everything between >>> COPY BELOW THIS LINE and <<< COPY ABOVE THIS LINE, remove the ? in ?Rc-Buggy, and paste it into Template:DebianInfo:

>>> COPY BELOW THIS LINE

<pre><onlyinclude>{{#switch: {{{Suite|{{{2|}}}}}} {{{Info|{{{1|}}}}}}
| oldoldstable Codename      = bullseye
| oldoldstable CodenameLink  = DebianBullseye
| oldoldstable Date          = 2025-08-09
| oldoldstable Version       = 11.11
|    oldstable Codename      = bookworm
|    oldstable CodenameLink  = DebianBookworm
|    oldstable Date          = 2026-01-10
|    oldstable Version       = 12.13
|       stable Codename      = trixie
|       stable CodenameLink  = DebianTrixie
|       stable Date          = 2026-03-14
|       stable Version       = 13.4
|      testing Codename      = forky
|      testing CodenameLink  = DebianForky
|      testing Date          = 2026-05-11
|      testing Version       = 
|     unstable Codename      = sid
|     unstable CodenameLink  = DebianSid
|     unstable Date          = 2026-05-11
|     unstable Version       = 
| experimental Codename      = rc-buggy
| experimental CodenameLink  = Debian?Rc-Buggy
| experimental Date          = 2026-05-11
| experimental Version       = 
| {{#switch: {{{Info|{{{1|}}}}}}
  | Codename
  | CodenameLink
  | Date
  | Version =
  | [[Category:ReviewRequired/InvalidDebianInfo]](unknown info type "{{{Info|{{{1|}}}}}}")
  }}
  {{#switch: {{{Suite|{{{2|}}}}}}
  | oldoldstable
  | oldstable
  | stable
  | testing
  | unstable
  | experimental =
  | [[Category:ReviewRequired/InvalidDebianSuite]](unknown suite "{{{Suite|{{{2|}}}}}}")
  }}
}}</onlyinclude></pre>

<templatedata>
{
    "description": "Information about a Debian release, usually called via e.g. {{DebianCodename}}",
    "params": {
        "Info": {
            "type": "line",
            "required": true,
            "description": "Type of information",
            "aliases": ["1"],
            "suggestedvalues": [
                "Codename",
                "CodenameLink",
                "Date",
                "Version"
            ]
        },
        "Suite": {
            "type": "line",
            "required": true,
            "description": "Version of Debian",
            "aliases": ["2"],
            "suggestedvalues": [
                "oldoldstable",
                "oldstable",
                "stable",
                "testing",
                "unstable",
                "experimental"
            ]
        }
    }
}
</templatedata>

<<< COPY ABOVE THIS LINE

See also

Admonitions

MoinMoin uses a variety of admonitions, many of which resemble MediaWiki's Template:Hint.

Still to do

  1. find the complete list of admonitions used on the site
  2. import or create appropriate templates
  3. decide how to style admonitions on the new site - do we want to discourage special formatting nowadays?

See also

MoinMoin automatically converts some words to links. The rules seem to be:

MediaWiki does not convert such words.

Find a complete regular expression for MoinMoin words, convert them to [[links]].

Some existing pages have a block near the end saying who has the copyright for the content.

We eventually decided all contributions should be CC-BY-SA 4.0 unless authors specify otherwise, which seems to be rare.

  1. if this doesn't occur often enough, or isn't challenging enough to treat as a special case, the converter should just handle it like any other case
  2. otherwise, convert copyright blocks to use the DebianFooter template described below

See also

<<FullSearch>> and <<FullSearchCached>>

MoinMoin's built-in <<FullSearch>> macro creates an <ol> with all the pages that match some search criteria. <<FullSearchCached>> is the same, but caches results to reduce server load. It may be possible to create a direct translation with one of the Category intersection extensions, or by pointing Extension:External_Data at the wiki's own search API, then rendering the result.

If you do /<<FullSearch(?:Cached)?+(.*?)>>/g on all pages in the wiki, the most common patterns are:

Still to do

See also

Footnotes

MoinMoin supports footnotes:

<<FootNote(text)>>

The nearest MediaWiki equivalent is the Cite extension.

  1. install the Cite extension
    • already installed on wiki2025.debian.org

  2. convert <<FootNote\((.*?)\)>> to <ref>$1</ref>

  3. don't add <references /> - references go at the bottom by default

Still to do

See also

Notable pages on the new wiki

Pages mentioned here are stored in a Salsa repository. This section discusses pages that will need to exist, but aren't discussed elsewhere on this page.

DebianHeader

All pages should be encouraged (and perhaps required) to start by transcluding a {{DebianHeader}} template. This is currently under construction at Template:DebianHeader. It will be put in the repository when it's reasonably complete.

DebianFooter

We may need to include a standard footer as well as a standard header. In particular, people who want to add their specific copyright statement should do so at the bottom of the page. This is currently under construction at Template:DebianFooter.

See also

Recommended extensions

See Special:Version for currently-installed software. Because extensions can be added and removed, the list below may include extensions that are currently present.

Cargo (not yet decided)

This has been discussed from time to time. It's likely to find several use cases, but people are worried about its security.

See also:

Cite

See Footnotes.

See also:

Emoticons

See Emoticons.

See also:

External Data

This would let us handle DebianBug links server-side (and much more besides).

See also:

Category intersection extensions (not yet decided)

It may be possible to migrate the <<FullSearch>> macro by pointing the External Data extension at the site's own search API. Otherwise, we may need to choose a category intersection extension.

MassEditRegex (not yet decided)

The migration to MediaWiki involved making common changes across many pages (e.g. changing all pages to use exactly four dashes to indicate a footer). MediaWiki's Extension:MassEditRegex provides a web-based interface, making this easier for authorised users to do.

See also:

SyntaxHighlight

This provides the equivalent of {{{#!highlight}}} code blocks.

See also:

UniversalLanguageSelector and Translate

These would provide a standard interface for handling translations.

See also:

WikiSEO or MetaMaster

WikiSEO or MetaMaster let you set arbitrary <meta> tags on a page by editing page contents. Similar extensions let you set <meta description> tags only, or put content in separate tables, which aren't as good.

Note that the recommendation calls these indirectly via a {{DebianHeader}} template, but users will doubtless find the underlying implementation and make pages that depend on its unique behaviour.

See also:

NoTitle

NoTitle hides the page title. At the time of writing, we haven't yet agreed whether we'll actually use this.

See also:

Ongoing jobs