Import from Wiki.js 2.x: links to files with parentheses in the name are not rewritten

[fredcamaral]

Description

The 2.x import renames asset files to the 3.x rules (alpha_(1).png becomes alpha-1.png) and, in finish, rewrites page links to the new names. An inline markdown link or image whose file name contains parentheses is not rewritten. It keeps pointing at the old name, and the image or file is broken after the import.

2.x keeps parentheses in uploaded file names (it lowercases them and turns spaces into underscores), and its editor inserts the path as stored. A file uploaded as Screenshot (1).png and inserted from the 2.x asset dialog gives ![screenshot_(1).png](/images/screenshot_(1).png), which is the form this misses.

Environment

• Source: Wiki.js 2.5.317, requarks/wiki:2 (sha256:e4708eed80c014449c0c8426c8d466c7a52a62131555bb44372fa48378b448b8), PostgreSQL 16.15. Package from the 2.x backup export (exporter 1.0.0), all content kinds.
• Target: Wiki.js 3.0.1, ghcr.io/requarks/wiki:3 (sha256:6e9987cc7f0f583f73591fbdf318fe94c6ba76616913e6c8f833b7a1960cd31d), PostgreSQL 18.6, fresh install. Import from Wiki.js 2.x with the default options (overwrite off, HTML converted to markdown).

Steps to reproduce

1. On a fresh 2.x, create the asset folder images and upload Alpha (1).png, India (6).png, Juliet (7).png, Charlie (3).png and Foxtrot one.png. Create the folder team_files and upload Bravo (2).pdf. 2.x stores them as alpha_(1).png, bravo_(2).pdf and so on.

2. Create a markdown page:

   ![alpha_(1).png](/images/alpha_(1).png)
   
   ![india_(6).png](/images/india_(6).png "India")
   
   [bravo_(2).pdf](/team_files/bravo_(2).pdf)
   
   <img src="/images/charlie_(3).png">
   
   ![foxtrot_one.png](/images/foxtrot_one.png)

3. Create a visual editor (ckeditor) page holding <p><img src="/images/juliet_(7).png"></p>.

4. Check that every image and file loads on 2.x (all return 200), export with the backup feature, and import the package into 3.0.1.

Actual behavior

The import's finish warning says pages were relinked ("[...] their links were rewritten to match"), but only some links were rewritten:

Link in the 2.x page	After the import	On 3.0.1
.png)	unchanged	/_files/images/alpha_(1).png 404
.png "India")	unchanged	/_files/images/india_(6).png 404
[bravo_(2).pdf](/team_files/bravo_(2).pdf)	unchanged	not the file (see below)
ckeditor <img src="/images/juliet_(7).png">	converted to .png), then unchanged	/_files/images/juliet_(7).png 404
<img src="/images/charlie_(3).png">	/images/charlie-3.png	200
	/images/foxtrot-one.png	200

Expected behavior

Every link to a renamed file is rewritten, as "Links follow the paths they point at" in dev/specs/wkbackup.md describes.

Cause

sourceLinkHrefs() reads an inline destination with /\]\(\s*([^\s<)][^\s)]*)/g (backend/helpers/linkRewrite.ts:223), which stops at the first ). On the lines above it returns /images/alpha_(1, /images/india_(6, /team_files/bravo_(2 and /images/juliet_\(7\. The resolver in #linkResolverFor (backend/models/import.ts:2000) finds no file under those names and returns null, so no replacement is made for them. The HTML src and reference-definition patterns read up to the closing quote or the next space, which is why those forms work.

Suggested fix

Read the destination the way CommonMark does, with balanced parentheses and backslash escapes. For example /\]\(\s*((?:[^\s()\\]|\\.|\((?:[^\s()\\]|\\.)*\))+)/g (one level of nesting) returns the full href for all four lines. Given the full href, the resolver handles the first three the way it already handles the HTML src form, and rewriteSourceLinks rewrites them (checked against the 3.0.1 helper).

The converted ckeditor link also needs its backslash escapes removed before it is resolved. sanitizeFileName (backend/models/assets.ts:148) treats \ as a path separator, so juliet_\(7\).png comes out as png and no file matches.

Related: links to non-image files and locale-prefixed images

These are separate from the parentheses. At render time only image sources are mapped to /_files/ (fileSrc in frontend/src/renderers/shared.js:82, used by the image rule at frontend/src/renderers/markdown.js:375), and a link keeps its href. The 2.x editor inserts a non-image file as a link, for example [plain.pdf](/images/plain.pdf). After the import that link renders as a page link, and /images/plain.pdf answers with the app shell. The file is only at /_files/images/plain.pdf. The 3.0.1 markdown editor inserts a picked non-image file in the same form, [title](/folder/file) (frontend/src/components/EditorMarkdown.vue:839).

An image link with a locale prefix, ![](/en/images/golf_two.png), which 2.x served, is rewritten to /en/images/golf-two.png and rendered as /_files/en/images/golf-two.png. That URL is 404; the file is at /_files/images/golf-two.png.

[NGPixel]

Fixed in 3.0.2