wordpress-to-kirby 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,13 @@
1
+ # Contributing
2
+
3
+ We welcome contributions from the community. Please open an issue before committing significant work.
4
+
5
+ All contributions to this project, in code or in prose, must be human-authored.
6
+
7
+ ## Local development
8
+
9
+ Running tests:
10
+
11
+ ```bash
12
+ npm run test
13
+ ```
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dan Burzo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -4,21 +4,115 @@ A Node.js-based command-line utility to convert a WordPress XML export to a dire
4
4
 
5
5
  ## Getting started
6
6
 
7
- Install from npm:
7
+ Install [`wordpress-to-kirby`](https://npmjs.com/package/wordpress-to-kirby/) from npm:
8
8
 
9
9
  ```bash
10
10
  npm install wordpress-to-kirby
11
11
  ```
12
12
 
13
- Or run with npx without installing:
13
+ Or run it with `npx` without installing:
14
14
 
15
15
  ```bash
16
16
  npx wordpress-to-kirby
17
17
  ```
18
18
 
19
+ Use `wordpress-to-kirby --help` for information on usage and available commands and options.
20
+
21
+ ## Commands
22
+
23
+ ### `wordpress-to-kirby generate`
24
+
25
+ Generate a Kirby CMS file structure from the provided XML file. Usage:
26
+
27
+ ```bash
28
+ wordpress-to-kirby generate [options] <wordpress-xml-file>
29
+ ```
30
+
31
+ ### `wordpress-to-kirby download`
32
+
33
+ Download the attachments found in the provided XML file. Usage:
34
+
35
+ ```bash
36
+ wordpress-to-kirby download [options] <wordpress-xml-file>
37
+ ```
38
+
19
39
  ## Options
20
40
 
21
- Use `wordpress-to-kirby --help` for a list of options.
41
+ ### General options
42
+
43
+ #### `-h, --help`
44
+
45
+ Prints out this help information.
46
+
47
+ #### `-v, --version`
48
+
49
+ Shows the program version.
50
+
51
+ #### `-o, --outdir`
52
+
53
+ Root directory to which to write the output, relative to the current working directory. Default: `wordpress-to-kirby`.
54
+
55
+ #### `--contentdir`
56
+
57
+ For the `download` command, point to the location of a `wp-content` directory from which to download attachments.
58
+
59
+ The path can be:
60
+
61
+ * an absolute or relative local path;
62
+ * a fully-qualified URL, including the `wp-content` segment, e.g. `https://mywebsite.local/wp-content/`
63
+
64
+ #### `--parse=<rules>`
65
+
66
+ Instructions to parse some fields, specified as `<key>=<parser>,<key>=<parser>,…`.
67
+
68
+ Supported parsers:
69
+
70
+ * `php`: deserialize PHP object;
71
+ * `yaml`: parse as YAML;
72
+ * `json`: parse as JSON;
73
+ * `html`: parse as HTML.
74
+
75
+ #### `--serialize=<rules>`
76
+
77
+ Instructions to serialize some fields, specified as `<key>=<serializer>,<key>=<serializer>,…`.
78
+
79
+ Supported serializers:
80
+
81
+ * `php`: serialize as PHP object;
82
+ * `yaml`: serialize as YAML;
83
+ * `json`: serialize as JSON;
84
+ * `html`: serialize as HTML.
85
+
86
+ ### `--exclude-fields=<fields>`
87
+
88
+ Exclude certain fields from the output, specified as a comma-separated list of fields.
89
+
90
+ ### `--include-fields=<fields>`
91
+
92
+ Only include certain fields from the output, specified as a comma-separated list of fields. When `--include-fields` is specified, the `--exclude-fields` option is ignored.
93
+
94
+ ### `--exclude-types=<types>`
95
+
96
+ Exclude certain post types from the output, specified as a comma-separated list of post types.
97
+
98
+ ### `--include-types=<types>`
99
+
100
+ Only include certain post types from the output, specified as a comma-separated list of post types.
101
+
102
+ When `--include-types` is specified, the `--exclude-types` option is ignored.
103
+
104
+ ## Keys extracted from the XML
105
+
106
+ The following keys are extracted from the top level of the WordPress XML export:
107
+
108
+ `title`, `link`, `pubDate`, `creator`, `guid`, `guid_isPermaLink`, `description`, `content`, `excerpt`, `post_id`, `post_date`, `post_date_gmt`, `post_modified`, `post_modified_gmt`, `comment_status`, `ping_status`, `post_name`, `status`, `post_parent`, `menu_order`, `post_type`, `post_password`, `is_sticky`, `attachment_url` (only populated for the `attachment` post type).
109
+
110
+ Fields from `<wp:postmeta>` are included in the output with the `postmeta*` prefix.
111
+
112
+ ## Keys generated from scratch
113
+
114
+ * `uuid: <string>`, containing 16 random alphanumeric characters.
115
+ * `template: 'attachment'` is added to attachments.
22
116
 
23
117
  ## Prior art
24
118
 
package/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
- import { readFile, writeFile, mkdir } from 'node:fs/promises';
3
- import { join, dirname, extname, relative } from 'node:path';
2
+ import { readFile, writeFile, copyFile, mkdir } from 'node:fs/promises';
3
+ import { join, dirname, extname, relative, sep } from 'node:path';
4
4
 
5
5
  import opsh from 'opsh';
6
6
  import { JSDOM } from 'jsdom';
@@ -75,18 +75,18 @@ commasep(options.serialize).forEach(pair => {
75
75
  serializers[key] = val;
76
76
  });
77
77
 
78
- const keys_to_include = new Set(commasep(options['include-keys']));
79
- const keys_to_exclude = new Set(options['include-keys'] ? [] : commasep(options['exclude-keys']));
78
+ const fields_to_include = new Set(commasep(options['include-fields']));
79
+ const fields_to_exclude = new Set(options['include-fields'] ? [] : commasep(options['exclude-fields']));
80
80
 
81
81
  const types_to_include = new Set(commasep(options['include-types']));
82
82
  const types_to_exclude = new Set(options['include-types'] ? [] : commasep(options['exclude-types']));
83
83
 
84
84
  function process_item(item) {
85
85
  let entries = Object.entries(item);
86
- if (keys_to_include.size) {
87
- entries = entries.filter(entry => keys_to_include.has(entry[0]));
88
- } else if (keys_to_exclude.size) {
89
- entries = entries.filter(entry => !keys_to_exclude.has(entry[0]));
86
+ if (fields_to_include.size) {
87
+ entries = entries.filter(entry => fields_to_include.has(entry[0]));
88
+ } else if (fields_to_exclude.size) {
89
+ entries = entries.filter(entry => !fields_to_exclude.has(entry[0]));
90
90
  }
91
91
  return Object.fromEntries(
92
92
  entries.map(entry => [
@@ -201,6 +201,9 @@ function extract(item) {
201
201
  }
202
202
  return (el ?? item).querySelector(sel);
203
203
  }
204
+
205
+ const post_type = parse_value('post_type', select('post_type', 'wp').textContent);
206
+
204
207
  return {
205
208
  title: parse_value('title', select('title').textContent),
206
209
  link: parse_value('link', select('link').textContent),
@@ -222,7 +225,7 @@ function extract(item) {
222
225
  status: parse_value('status', select('status', 'wp').textContent),
223
226
  post_parent: parse_value('post_parent', select('post_parent', 'wp').textContent),
224
227
  menu_order: parse_value('menu_order', select('menu_order', 'wp').textContent),
225
- post_type: parse_value('post_type', select('post_type', 'wp').textContent),
228
+ post_type,
226
229
  post_password: parse_value('post_password', select('post_password', 'wp').textContent),
227
230
  attachment_url: parse_value('attachment_url', select('attachment_url', 'wp')?.textContent),
228
231
  is_sticky: parse_value('is_sticky', select('is_sticky', 'wp').textContent),
@@ -232,7 +235,8 @@ function extract(item) {
232
235
  acc['postmeta' + key] = parse_value('postmeta' + key, value);
233
236
  return acc;
234
237
  }, {}),
235
- uuid: uuid()
238
+ uuid: uuid(),
239
+ template: post_type === 'attachment' ? 'attachment' : undefined
236
240
  }
237
241
  }
238
242
 
@@ -276,6 +280,7 @@ if (command === 'generate') {
276
280
 
277
281
  const blueprints_path = join(outdir, 'site', 'blueprints');
278
282
  await mkdir(join(blueprints_path, 'pages'), { recursive: true });
283
+ await mkdir(join(blueprints_path, 'files'), { recursive: true });
279
284
 
280
285
  Object.keys(metadata.types).forEach(key => {
281
286
  metadata.types[key] = Array.from(new Set(metadata.types[key])).sort();
@@ -286,35 +291,55 @@ if (command === 'generate') {
286
291
  };
287
292
  return acc;
288
293
  }, {});
289
- writeFile(join(blueprints_path, 'pages', key + '.yml'), dump({
290
- tabs: {
291
- fields: {
292
- label: 'Fields',
293
- sections: {
294
- fields: {
295
- type: 'fields',
296
- fields: blueprint_content
297
- }
298
- }
299
- },
300
- pages: {
301
- label: 'Pages',
302
- sections: {
303
- pages: {
304
- type: 'pages'
294
+
295
+ if (key === 'attachment') {
296
+ const blueprint_dest = join(
297
+ blueprints_path,
298
+ 'files',
299
+ key + '.yml'
300
+ );
301
+
302
+ writeFile(blueprint_dest, dump({
303
+ fields: blueprint_content
304
+ }));
305
+
306
+ } else {
307
+ const blueprint_dest = join(
308
+ blueprints_path,
309
+ 'pages',
310
+ key + '.yml'
311
+ );
312
+
313
+ writeFile(blueprint_dest, dump({
314
+ tabs: {
315
+ fields: {
316
+ label: 'Fields',
317
+ sections: {
318
+ fields: {
319
+ type: 'fields',
320
+ fields: blueprint_content
321
+ }
305
322
  }
306
- }
307
- },
308
- files: {
309
- label: 'Files',
310
- sections: {
311
- files: {
312
- type: 'files'
323
+ },
324
+ pages: {
325
+ label: 'Pages',
326
+ sections: {
327
+ pages: {
328
+ type: 'pages'
329
+ }
330
+ }
331
+ },
332
+ files: {
333
+ label: 'Files',
334
+ sections: {
335
+ files: {
336
+ type: 'files'
337
+ }
313
338
  }
314
339
  }
315
340
  }
316
- }
317
- }));
341
+ }));
342
+ }
318
343
  });
319
344
 
320
345
 
@@ -342,74 +367,153 @@ if (command === 'generate') {
342
367
  await writeFile(join(blueprints_path, 'site.yml'), dump(default_blueprint));
343
368
 
344
369
  await writeFile(join(outdir, 'metadata.json'), JSON.stringify(metadata, null, '\t'));
345
- } else if (command === 'download') {
346
- console.error('Not implemented yet, exiting.');
347
- process.exit(1);
370
+ }
371
+
372
+ if (command === 'download') {
373
+
374
+ const contentdir = options.contentdir ?
375
+ (URL.canParse(options.contentdir) ?
376
+ new URL(options.contentdir) :
377
+ options.contentdir
378
+ ) : null;
379
+
380
+ const fetched = new Set();
381
+
382
+ for await (let item of items.filter(it => it.post_type === 'attachment')) {
383
+ const attachment = process_item(item);
384
+ const dest = outpath(attachment).replace(/\.txt$/, '');
385
+ if (contentdir) {
386
+ const pathname = new URL(attachment.attachment_url).pathname
387
+ .split('/')
388
+ .filter(p => p && p !== 'wp-content')
389
+ .join(sep);
390
+ if (typeof contentdir === 'string') {
391
+ await copyFile(join(contentdir, pathname), dest);
392
+ } else {
393
+ const url = new URL(pathname, contentdir);
394
+ if (fetched.has(url)) {
395
+ console.log(`Already fetched, skipping: ${url}`);
396
+ } else {
397
+ console.log(`Fetching: ${url}`);
398
+ await mkdir(dirname(dest), { recursive: true });
399
+ await writeFile(
400
+ dest,
401
+ (await fetch(url)).body
402
+ );
403
+ console.log(`Fetched: ${url}`);
404
+ fetched.add(url);
405
+ }
406
+ }
407
+ } else {
408
+ if (fetched.has(attachment.attachment_url)) {
409
+ console.log(`Already fetched, skipping: ${attachment.attachment_url}`);
410
+ } else {
411
+ console.log(`Fetching: ${attachment.attachment_url}`);
412
+ await mkdir(dirname(dest), { recursive: true });
413
+ await writeFile(
414
+ dest,
415
+ (await fetch(attachment.attachment_url)).body
416
+ );
417
+ console.log(`Fetched: ${attachment.attachment_url}`);
418
+ fetched.add(attachment.attachment_url);
419
+ }
420
+ }
421
+
422
+ }
348
423
  }
349
424
 
350
425
  function printHelp() {
351
426
  console.log(`wordpress-to-kirby:
352
427
 
353
- transform a WordPress XML export
354
- into a directory of Kirby CMS files.
428
+ transform a WordPress XML export into a directory of Kirby CMS files.
355
429
 
356
430
  Usage:
357
431
 
358
- wordpress-to-kirby <command> <xml-file> <options>
432
+ wordpress-to-kirby generate [options] <wordpress-xml-file>
433
+ wordpress-to-kirby download [options] <wordpress-xml-file>
359
434
 
360
- Commands:
435
+ Commands available:
361
436
 
362
437
  generate
363
438
  Generate a Kirby CMS file structure from the provided XML file.
364
439
 
365
440
  download
366
- Download attachments. Not implemented.
441
+ Download attachments.
367
442
 
368
- Options:
443
+ Options available:
369
444
 
370
445
  -h, --help
371
- Print out this help information.
446
+
447
+ Prints out this help information.
372
448
 
373
449
  -v, --version
374
- Show the program version.
450
+
451
+ Shows the program version.
375
452
 
376
453
  -o, --outdir
377
- Root directory to output to, relative to CWD.
454
+
455
+ Root directory to which to write the output,
456
+ relative to the current working directory.
457
+
378
458
  Default: 'wordpress-to-kirby'
379
459
 
460
+ --contentdir
461
+
462
+ For the 'download' command, point to the location
463
+ of a 'wp-content' directory from which to download attachments.
464
+
465
+ The path can be:
466
+
467
+ * an absolute or relative local path;
468
+ * a fully-qualified URL, including the 'wp-content' segment,
469
+ e.g. https://mywebsite.local/wp-content/
470
+
380
471
  --parse=<rules>
381
- Instructions to parse some fields, in the form of:
472
+
473
+ Instructions to parse some fields, specified as:
382
474
  "<key>=<parser>,<key>=<parser>,…"
475
+
383
476
  Supported parsers:
384
- php: deserialize PHP object.
385
- yaml: parse as YAML.
386
- json: parse as JSON.
387
- html: parse as HTML.
388
- Prefix post meta fields with "postmeta".
477
+ * php: deserialize PHP object.
478
+ * yaml: parse as YAML.
479
+ * json: parse as JSON.
480
+ * html: parse as HTML.
389
481
 
390
482
  --serialize=<rules>
391
- Instructions to serialize some fields, in the form of:
483
+
484
+ Instructions to serialize some fields, specified as:
392
485
  "<key>=<serializer>,<key>=<serializer>,…"
393
- Supported parsers:
394
- php: serialize as PHP object.
395
- yaml: serialize as YAML.
396
- json: serialize as JSON.
397
- html: serialize as HTML.
398
- Prefix post meta fields with "postmeta".
399
486
 
400
- --exclude-keys=<keys>
401
- Exclude certain keys from the output. Comma-separated.
487
+ Supported serializers:
488
+ * php: serialize as PHP object.
489
+ * yaml: serialize as YAML.
490
+ * json: serialize as JSON.
491
+ * html: serialize as HTML.
492
+
493
+ --exclude-fields=<fields>
494
+
495
+ Exclude certain fields from the output, specified as a
496
+ comma-separated list of fields.
497
+
498
+ --include-fields=<fields>
402
499
 
403
- --include-keys=<keys>
404
- Only include certain keys from the output. Comma-separated.
405
- When '--include-keys' is specified, any '--exclude-keys' is ignored.
500
+ Only include certain fields from the output, specified as a
501
+ comma-separated list of fields.
502
+
503
+ When '--include-fields' is specified, the '--exclude-fields'
504
+ option is ignored.
406
505
 
407
506
  --exclude-types=<types>
408
- Exclude certain post types from the output. Comma-separated.
507
+
508
+ Exclude certain post types from the output, specified as a
509
+ comma-separated list of post types.
409
510
 
410
511
  --include-types=<types>
411
- Only include certain post types from the output. Comma-separated.
412
- When '--include-types' is specified, any '--exclude-types' is ignored.
512
+ Only include certain post types from the output, specified as a
513
+ comma-separated list of post types.
514
+
515
+ When '--include-types' is specified, the '--exclude-types'
516
+ option is ignored.
413
517
 
414
518
  Keys extracted from the XML:
415
519
 
@@ -424,11 +528,12 @@ Keys extracted from the XML:
424
528
 
425
529
  Post metadata:
426
530
 
427
- Fields from <wp:postmeta> not starting with an underscore
428
- are included in the output with the 'postmeta*' prefix.
531
+ Fields from '<wp:postmeta>' are included in the output
532
+ with the 'postmeta*' prefix.
429
533
 
430
534
  Keys generated from scratch:
431
535
 
432
- uuid — sixteen random alphanumeric characters.
536
+ uuid — sixteen random alphanumeric characters.
537
+ template: 'attachment' — added to attachments only.
433
538
  `);
434
539
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "wordpress-to-kirby",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "A CLI to convert WordPress XML to Kirby CMS files",
5
5
  "homepage": "https://github.com/tocmai/wordpress-to-kirby#readme",
6
6
  "bugs": {