Migrate from DokuWiki to XWiki

Migrate from DokuWiki to XWiki: what moves and what sets the effort

The move from DokuWiki to XWiki is driven by content conversion and cleanup far more than by installing the software. Effort depends on how many pages and attachments you hold, how varied the DokuWiki syntax is across those pages, which plugins your site relies on, and how permissions and namespaces map to XWiki spaces and rights. Plan the project around those four inputs before you size any infrastructure. This is a wiki-to-wiki path. It uses XWiki's filter stream importers together with the DokuWiki tools maintained in the xwiki-contrib repositories on GitHub. Those tools read DokuWiki's page files and attachments and convert them into XWiki content through the filter stream framework. Confirm the exact tool versions, the XWiki version they target, and the list of DokuWiki syntax they support against the repository before you write a plan, because support changes between releases and gaps are easy to miss. Start with an inventory. List every namespace, count pages and media files, and note which DokuWiki plugins render content (tables, code, diagrams, math, custom macros). Each plugin that changes page output needs a decision: convert it to an XWiki macro, replace it with a native feature, or retire it. Also record who can read and edit each namespace, because DokuWiki's ACL file is not a one-to-one match for XWiki groups and rights, and you will need to rebuild those rules by hand. Run a test import into a non-production XWiki instance before any cutover. Use a representative sample that includes your worst syntax cases, your largest namespace, a page with many images, and pages with internal links. Compare rendered output with the source wiki, check internal links and media references, and record every page that needs manual rework. The volume of that rework from the test run is the most reliable estimate of the cleanup effort you will face at full scale. When you request a quote from a partner or estimate internally, ask for the inventory method, the syntax and plugin coverage check, the permission mapping approach, the number of test import cycles, and what manual cleanup is included versus left to your editors. Ask which costs recur after cutover, such as hosting, upgrades and support, and which are one-time, such as conversion and rebuild work.

Which DokuWiki features map cleanly to XWiki and which need rebuilding

This table compares DokuWiki features with their closest XWiki equivalents and states what to expect from the migration. Read the migration note in each row to see whether the importer is expected to convert the item, a manual step is needed, or a test import must confirm the behavior first. Where the documentation for a conversion is unclear, the row asks you to confirm behavior rather than assume a match.

DokuWiki feature	XWiki equivalent	Migration note
Pages	XWiki documents inside spaces	Body text is expected to convert. Confirm titles, page names and content in a test import.
Namespaces	XWiki spaces and nested pages	Manual step. Decide how each namespace level maps to a space or parent page before importing.
Media files	XWiki attachments on documents	Confirm that files, file names and attachment links carry over. Plan a manual check of media references.
Page revisions	XWiki document version history	Confirm in a test import how many old revisions carry over. Keep an archive copy of the source wiki.
ACL rules	XWiki rights on spaces and pages	Manual rebuild. Map each DokuWiki access level to XWiki rights and verify with test accounts.
Users and groups	XWiki users and groups	Manual step. Confirm how accounts and passwords are handled, and plan group membership separately.
Plugins	XWiki extensions, macros or custom development	Rebuild manually. List every plugin in use and find an equivalent extension or macro for each one.
Templates	XWiki templates and skins	Manual rebuild of layout and styling. Page templates need redesign as XWiki templates.
Internal links	XWiki wiki links	Confirm in a test import. Check namespace-style and relative links after the import completes.

Documented DokuWiki import paths into XWiki

The documented route into XWiki for DokuWiki content combines the xwiki-contrib DokuWiki tools with the XWiki filter stream importers. The cards below describe what each part expects, what it converts and where it stops, so you can judge the route before planning a test import. Treat every tool name, release and supported DokuWiki version as something to confirm against the repositories and XWiki documentation.

DokuWiki tools and their inputs

The xwiki-contrib DokuWiki tools are the entry point for this route. Identify the repository that hosts each tool, then record the exact input each one expects, such as a page directory or a dump in a specific form. Your export step must produce that input. Do not assume an export format that the tool documentation does not describe.

Filter stream importer role

The XWiki filter stream importers take converted content and write it into XWiki pages and attachments. They run after the DokuWiki tools in the chain, so a failure can originate in either stage. Confirm which filter stream format the DokuWiki route produces and check it against the XWiki documentation for the release line you plan to target.

Syntax parser conversion scope

The syntax parser maps the DokuWiki markup it documents to XWiki syntax. Markup outside that documented mapping, such as plugin syntax or custom macros, may pass through as text or fail to convert. Scan your source pages for the markup your wiki actually uses, then compare that list with the parser's documented coverage before you commit to this route.

Where the route stops

Expect the documented route to stop at content it does not describe, such as plugin output, access control lists, user accounts, group memberships and page history. Confirm in the tool documentation which of these it carries over. Anything left behind becomes manual work or a separate project, and that boundary should be written into the scope before the test import begins.

Manual cleanup after conversion

Converted pages still need review. Look for broken internal links, namespace paths that map to new page hierarchies, images that did not move and macros rendered as plain text. Estimate review effort from the page count and the amount of custom markup in the wiki, and confirm with any partner whether cleanup falls in their scope or yours.

Version checks before planning

Before estimating effort, confirm three things against the repositories and XWiki documentation: the current tool names and releases, the DokuWiki versions the tools support, and the XWiki release line you target. Record that combination in the migration plan so the test import and the cutover use the same versions.

How the DokuWiki importer converts pages during a DokuWiki to XWiki migration

The importer decides what your pages look like after cutover, so the team should understand the conversion chain before running anything at scale. In plain terms, the tool reads DokuWiki files from disk, parses the DokuWiki markup in each page into an internal structure, produces XWiki content from that structure, and writes the result through the XWiki import stream. Each stage can lose or alter information, so a problem in the output may originate in any of them. Confirm with the tool's documentation which DokuWiki data directories it reads, such as page text, media files and metadata, and which it skips. Anything it skips will not appear in a test import, which makes that gap easy to miss.

A test import on a representative sample reveals the problems that matter most. Start with page titles. DokuWiki derives titles from file names and from headings in the text, while XWiki page names follow their own character and uniqueness rules, so titles may change or collide. Next, check internal link targets. Links to namespaces, section anchors and pages with unusual names are the most likely to break, and a broken link often looks correct in the source markup. Then confirm namespace-to-space placement, verifying that nested DokuWiki namespaces land as the nested XWiki spaces your information architecture expects, with start pages resolving as intended.

Attachments and revision handling need their own checks. Confirm that media files referenced by pages are attached to the correct pages and that image and file references still resolve after import. Decide with content owners whether page history is carried over or only the current version is kept, then verify what the test run actually preserves. DokuWiki stores older revisions separately from current pages, and the importer may not map every revision. Also review how authors and timestamps appear on imported pages, because those fields often feed audit trails and content review processes that your compliance team relies on.

Conversion results depend on the DokuWiki syntax your site actually uses. Plugins, custom markup, table variants and macros outside the core syntax may be passed through unchanged, converted partly, or dropped. Build an inventory of syntax elements by sampling pages from each namespace, then make sure the test set includes pages that use each element. Treat the test output as the acceptance baseline. Agree in writing which differences are acceptable, which need manual cleanup before cutover, and which block the bulk run until the importer or the source content is changed.

What needs manual cleanup after the import

DokuWiki pages use their own markup, and most sites add plugins that extend it with tables, boxes, diagrams or custom blocks. The importer and syntax parser convert the core markup they recognize, but anything a plugin adds needs review. Converted pages often look correct at a glance while small losses hide in lists, nested tables or preformatted blocks.

Find it: Search the source export for the plugin tags your site uses. Build the list from the installed plugin directory, then compare the counts with the import log.
Sample by plugin: Render a sample page from each plugin-heavy namespace in XWiki and compare it side by side with the DokuWiki original.
Check structure: Nested lists, merged table cells and column alignment are the usual casualties, so review them by eye.
Decide the replacement: Content owners decide whether each plugin block becomes an XWiki macro, a plain table or plain text.

Confirm in the importer documentation which core syntax is covered before you size this review.

Sequence for a DokuWiki to XWiki move with a test import, parallel run and cutover

This sequence moves a DokuWiki site into XWiki in seven phases, each with defined inputs, a decision and an exit check. The test import and pilot surface conversion gaps and permission problems before users depend on the new wiki. The parallel run and cutover keep one system of record at a time, with a rollback point until the move is signed off.

Inventory namespaces, pages, media, plugins and users
Your team or the partner lists every namespace, page, media file, installed plugin, user and ACL group from the DokuWiki data directory and its configuration files. Pages and media are counted per namespace, and each plugin is marked as converted, replaced or dropped, because plugin syntax cannot be assumed to convert. The inventory also maps DokuWiki users and groups to the identity source XWiki will use. The step is complete when each namespace owner has signed off the list and no plugin is left without a disposition.
Test import into a non-production XWiki
Import a frozen snapshot of the DokuWiki files into a non-production XWiki built from the image line you have chosen. The inputs are the inventory, the snapshot and the test instance. Compare sample pages, internal links, media references, headings, tables and macros against the source, and log each conversion defect with an owner. The decision is which namespaces convert acceptably and which need manual cleanup or a scripted fix. The step closes when the defect log is complete and namespace owners have reviewed every sampled page.
Repair gaps and repeat the test import
Adjust the mapping, write scripted fixes for recurring syntax and rework plugin output the importer does not convert. Each run starts from a clean XWiki instance so results are reproducible and comparable. Record the importer version and any xwiki-contrib tooling used, and confirm both with the vendor or the community project before relying on them. The exit check is a run that produces no new defects in the sampled namespaces, plus a documented list of manual edits that editors will make after cutover.
Pilot with a named user group
Give a named group of editors and readers access to the pilot namespaces in the test XWiki, with permissions rebuilt from the DokuWiki ACL inventory. The group works through a written checklist covering search, edits, attachments, navigation and the pages they use most. Their findings go into the defect log and may change permission rules or the import mapping. The decision is whether the approach is fit for the wider user base. The exit check is a signed pilot report listing open issues, each with an owner and a fix date agreed before cutover.
Run a parallel period with reconciliation
Keep DokuWiki readable while the pilot namespaces are used in XWiki, and agree a written rule for where new edits are made during this period. Reconcile changes by exporting DokuWiki edits made since the last import, comparing them with XWiki, and merging or re-importing them as the rule states. Track each reconciliation in a log with the page, author, date and outcome. The decision is which wiki is the system of record for each namespace at each point. The exit check is an empty reconciliation backlog and namespace owner sign-off that all changes are accounted for.
Cut over in a controlled window
Run a final delta import in an agreed change window, set DokuWiki to read-only and verify the migrated content in the production XWiki. Before the window, write go and no-go criteria, back up the DokuWiki data and the XWiki instance, and test restoring that backup to confirm the rollback point. Confirm how old DokuWiki URLs will be handled, since external links may break. The decision is go or no-go against the written criteria. The exit check is a verified production import, a tested rollback point and a written record of the cutover sign-off.
Decommission DokuWiki and keep a read-only archive
After the agreed post-cutover period, switch off the live DokuWiki and keep a read-only archive of the data directory, configuration, media and user records. Confirm retention obligations with the records owner, choose an archive format and location that owner can read, and restrict access to the archive. The decision is when the live site is switched off and who approves it. The exit check is a test restore or an open of the archive, confirmed access controls on it, and a signed decommission record naming the archive location and retention owner.

What drives cost and duration in a DokuWiki to XWiki migration

This table lists the factors that change effort in a DokuWiki to XWiki move, how each one raises or lowers the work, and what to gather before asking for a fixed-scope quote. Use it as a checklist for your inventory. The main takeaway is that syntax variety, plugin use and access rules usually move the estimate more than raw page count.

Driver	Effect on effort	What to provide for scoping
Pages and namespaces	Each page needs import checks, and deep namespace trees need a planned mapping to XWiki spaces.	Page count per namespace, the namespace tree, and pages that are stale or can be archived.
Media volume	Media files must be transferred and relinked, so file count and total size drive import time and storage.	File counts, total size by namespace, file types, and whether old media revisions must be kept.
Syntax variety and plugin use	Standard markup converts most reliably. Plugin macros, custom syntax and embedded HTML usually need manual rebuilding.	Enabled plugins, custom syntax or templates, and a sample of pages that use each one.
Access control complexity	Page-level ACLs and groups must be rebuilt as XWiki rights and groups, which adds design and test time.	The ACL configuration, the group list, and who may read or edit each namespace.
Linked systems	Single sign-on, search and file storage each add configuration, testing and cutover steps.	Names and versions of identity, search and storage systems, and the integration method each one uses.
Reviewers for content sign-off	Each reviewer adds a review cycle, and unclear ownership often delays cutover more than conversion does.	Named reviewers per area, their availability windows, and the acceptance criteria they will sign.
Who is paid for each cost component	Conversion, cleanup, testing and cutover support are separate lines. Hosting and support recur after go-live.	Ask whether consulting is quoted per day (XWiki SAS lists 1200 EUR per day, xwiki.com pricing) and which support plan it requires.

What your team must provide for the DokuWiki to XWiki migration

Before any import runs, your team must name a content owner for each DokuWiki namespace. That person decides which pages are current, which are archived, and which should not move at all. Each owner also signs off the migrated copy in XWiki, so the import is judged against content someone in the business understands. Without named owners, cleanup stalls, and nobody can say when a space is ready for cutover. Agree on the sign-off method early, such as a checklist of pages, links and attachments per namespace, and record who approved each one.

The team also needs access to a recent copy of the DokuWiki site for test imports. That copy should include the page files, the media directory, and the metadata that DokuWiki keeps for page history and media versions. Decide now whether you keep full page history, only the latest revision, or history for selected namespaces. Decide the same for media files and their old versions. These choices change the size of the import, the volume of cleanup and the length of the test cycle, so they should be written down as scope before the first test run.

If single sign-on is part of the plan, identify the source of identities before the import. Confirm whether users come from Active Directory, LDAP, or an OpenID Connect provider, and who owns that directory. XWiki users, groups and rights are created or mapped during the migration, so the identifiers in DokuWiki must match accounts that will exist after cutover. The xwiki-contrib OpenID Connect extension can authenticate users against an external OIDC provider, and XWiki Pro lists Active Directory and Azure Active Directory SSO applications. Confirm which option fits your environment and license model with the vendor before you design the user mapping.

Internal staff can run the documented import themselves if they have the Linux, XWiki and Java administration skills, and the time to test. That route takes on the test imports, triage of conversion gaps, mapping of users and groups, cleanup work, the cutover runbook, and ongoing ownership of extension versions and upgrades. A partner adds scoped delivery under a written plan, a repeatable test cycle, defined acceptance criteria, and a support path after cutover. Cost has one-time parts (analysis, import, cleanup, cutover) and recurring parts (support and upgrades). Ask any provider for the cost of each part separately. For reference, XWiki SAS lists consulting at 1200 EUR per day, which requires a Business or Enterprise support plan.

What usually goes wrong in a DokuWiki to XWiki move and how to prevent it

Most problems in this move come from a few predictable places: how page paths and links map after import, how DokuWiki plugin markup is read, and how access is rebuilt. Each risk below pairs with a check during the test import, a pilot space or a parallel run, so issues surface before the cutover date is fixed.

Broken internal links after namespace changes

DokuWiki namespaces are directories of page files, while XWiki organizes content into spaces and nested pages, so links written against the old paths can point nowhere after import. Run the test import, then crawl the imported pages with a link checker and sample pages from every top-level namespace. Confirm in the importer documentation how relative and absolute links are rewritten and how names with special characters are handled before you fix a naming scheme.

Plugin syntax that never converts

Plugin markup, such as custom boxes, tags or data views, is the most likely content to fall outside what the syntax parser converts. It may arrive as plain text, escaped code or empty blocks that look fine in a list view. Inventory every plugin from the configuration and the page sources, then test one page per plugin in the test import. For each plugin, decide whether to rewrite by hand, map to an XWiki macro or keep as archived text.

Lost or misplaced media

DokuWiki keeps images and files in a media area separate from page text, and pages reference them by path. If media lands somewhere the converted pages do not expect, images show as broken or attach to the wrong page. Compare the count of media files in the source with the imported attachments, then open sample pages that embed images and download links. Check file names with spaces, uppercase extensions and duplicate names during the pilot.

Permissions rebuilt incorrectly

DokuWiki access control lists are set per namespace and per page and reference users and groups from its own configuration. XWiki uses its own rights model based on users, groups, spaces and pages, so the mapping is a design task that must be written down before import. Build the group mapping and target rights for two or three sample spaces, import users, and log in as one account from each group to test read, edit and admin access. Confirm how XWiki applies inherited rights before the parallel run.

Stale content migrated without review

A full export carries drafts, abandoned pilots and pages nobody has opened in years. Moving all of it makes search noisy and adds review work during cutover. Agree a retention rule before the test import, such as archiving pages not edited within a period the content owners set. Owners then sign off each pilot space, and the archive is kept read-only and linked from the new home so nothing is lost silently.

Cutover without a rollback path

A single switch from DokuWiki to XWiki leaves no way back if users find missing pages after launch. Keep the DokuWiki instance running in read-only mode, record each import run with its inputs, and agree a freeze window in which late edits are merged or redone. Rehearse the rollback during the pilot: restore the redirect, reopen the old wiki for editing and confirm who makes the go or no-go call and against which criteria.

Questions buyers ask before a DokuWiki to XWiki migration

How much does a DokuWiki to XWiki migration cost?

The cost depends on the scope you agree in writing, and the main drivers are the number of pages and namespaces, how much DokuWiki plugin syntax and custom markup needs conversion, the volume of media files, whether page revisions must come across, how users and ACL rules map to XWiki groups and rights, and how many test imports the cleanup requires. These are mostly one-time costs. Recurring costs come from hosting, operations and XWiki subscriptions. If XWiki SAS provides any part of the work, its published consulting rate is 1200 EUR per day, which requires a Business or Enterprise support plan, and its training rate is 1500 EUR per day. Its subscription tiers are Starter (up to 25 users, XWiki Cloud only), Basic (up to 1,000 users), Business (up to 10,000 users) and Enterprise (unlimited users), and XWiki SAS states that cloud and on-premises pricing is the same. Ask any partner for a quote that separates one-time work from recurring costs and lists each assumption about content volume.

How long does a DokuWiki migration to XWiki take?

Duration is driven by content volume and complexity, the number of cleanup passes, the amount of custom syntax or plugin content, the number of user and permission rules to rebuild, and how many stakeholders must review test imports. Calendar time also depends on your change windows and approval steps, which often matter more than technical effort. A sound plan has distinct phases for inventory, a first test import, content review, a second test import, a parallel run and cutover. No duration should be accepted without a written timeline tied to a defined scope. Ask for the phases, the review effort each phase needs from your team, and the assumptions behind the schedule, including how many pages are expected to need manual fixes.

What must our team provide for a DokuWiki to XWiki migration?

Your team needs to provide a named business owner who can make content and access decisions, read access to the DokuWiki installation (its configuration, the pages directory, the media directory and, if history is wanted, the old revisions directory), a current list of users and groups with their roles, and a list of namespaces that should be kept, merged, archived or retired. You also need a target XWiki environment with agreed hosting, backup and access controls, and reviewers who will check test imports against real pages. Plan for people who know the wiki's most-used content, since they catch errors that automated checks miss. Confirm the exact export and access steps with the current documentation of the xwiki-contrib DokuWiki tooling before the project starts.

Can our internal staff migrate DokuWiki to XWiki without a partner?

Yes, a capable internal team can run the migration, provided it has people who can operate XWiki (installation, extensions, permissions and backups), can work with the DokuWiki export and the xwiki-contrib tooling, and can allocate time for repeated test imports and manual cleanup. The usual gaps are less technical than they look: nobody owns the decision on which content to retire, the cutover plan has no tested rollback, and cleanup work stalls once the initial import looks acceptable. A partner adds value where the wiki has heavy custom syntax, many permission rules, or tight cutover constraints. Compare the internal effort, including reviewer time, against a written, fixed-scope proposal before deciding.

Does a DokuWiki to XWiki migration keep page history and media files?

Confirm this for your version of the tooling before you commit to a plan, because the answer depends on what the xwiki-contrib DokuWiki importer and syntax parser support. Check whether current page content, media files, page revisions, namespaces and attachment links are imported, and how each is represented in XWiki afterward. Do not assume the behavior of other migration tools. For example, XWiki SAS's Confluence Migrator Pro keeps page history but not attachment history, but it is built for Confluence and does not describe DokuWiki behavior. Run a test import on a copy of your largest namespace and compare revisions and media links against the source before you decide what history you will keep.

How does a parallel run work during a DokuWiki to XWiki cutover?

During a parallel run, both wikis are available for a defined period while the team checks that content, links and access rules behave as expected in XWiki. The key decision is the source of truth: either DokuWiki stays authoritative and changes are re-imported, or edits move to XWiki and DokuWiki becomes read-only. Most teams prefer the second option because it avoids two sets of edits, but the choice must be written down with the editing freeze, the owner of conflicting changes and the criteria for ending the run. Plan a final content sync in the cutover window, then compare page counts, link checks and sample reviews. Ask your partner or internal lead to document this plan before the first production import.

How do you roll back a failed XWiki cutover?

A rollback plan starts before cutover, with the DokuWiki installation, its data directories and its configuration preserved unchanged and with a verified backup taken before the final import. Also back up the XWiki database and files so you can return to a known state if the first production import goes wrong. Define the conditions that trigger a rollback, the person who decides, and the steps to restore user access to DokuWiki, including DNS, reverse proxy or bookmark changes. Test the rollback on a staging copy, because an untested rollback often fails at the moment it is needed. Confirm the restore procedure and its duration with your team before the cutover date is set.

How DeployOpen scopes, runs and supports a DokuWiki to XWiki migration

DeployOpen scopes the DokuWiki to XWiki move around your page inventory, syntax, users and permissions, then runs a test import before anything reaches production. Tool coverage is checked against your own export, so the written plan lists what converts automatically and what needs manual cleanup. The work runs in infrastructure you control, and ongoing support is available as a retainer.

How we scope

Inventory DokuWiki namespaces, pages, media files, users and ACL rules before any tooling is chosen.
Map which DokuWiki syntax and plugins appear in your content and which need manual rework in XWiki.
Agree the fixed scope, deliverables and cutover conditions in writing before migration work starts.

How we build

Run the xwiki-contrib DokuWiki tools against a copy of your export in a test XWiki instance.
Review converted pages for lost formatting, broken internal links and media that did not carry over.
Rebuild the space structure, groups and rights in XWiki to match the access model your team approved.

How we hand over

Document what converted automatically, what was cleaned up by hand and what was left out.
Provide test import results, a reconciliation checklist and the final cutover runbook for your team.
Agree a dated freeze of DokuWiki edits so the final import matches the content users see.

How we support

Keep a rollback path to the DokuWiki server until your team signs off on the migrated XWiki content.
Offer post-cutover help with broken links, permission questions and cleanup requests as a retainer.
Confirm the XWiki version, database variant and hosting model with your team before deployment starts.

Migrate from DokuWiki to XWiki