@doki-land/doki-migrate

v0.0.0

Published

23 days ago

Doki Engine 内容迁移工具

Downloads

0High
0Medium
0Low

galaster

doki migrate static-site-generator

🔄 Doki Migrate

📦 从其他静态站点生成器和 CMS 迁移内容到 Doki Engine

📖 简介

@doki-land/doki-migrate 是 Doki Engine 的内容迁移工具，帮助用户从 Hugo、Hexo、Jekyll、WordPress 等平台平滑迁移到 Doki Engine。

✨ 特性

🔄 多平台支持 - 支持 Hugo、Hexo、Jekyll、WordPress 迁移
📝 Frontmatter 转换 - 支持 YAML、TOML、JSON 格式互转
🎨 模板转换 - 自动转换模板语法
📁 批量处理 - 支持批量迁移整个项目
🔧 灵活配置 - 可自定义迁移规则

📦 安装

pnpm add @doki-land/doki-migrate

🚀 快速开始

基础用法

import { migrate, createMigrator, type MigrateOptions } from "@doki-land/doki-migrate";

const options: MigrateOptions = {
  source: "./hugo-content",
  output: "./doki-content",
  convertFrontmatter: true,
  convertTemplates: true,
};

// 使用便捷函数
const result = await migrate("hugo", options);

// 或使用迁移器实例
const migrator = createMigrator("hugo");
const result = await migrator.migrate(options);

console.log(`迁移完成！处理 ${result.files.length} 个文件`);

支持的迁移器

| 平台 | 标识符 | 说明 | |------|--------|------| | Hugo | hugo | Hugo 静态站点生成器 | | Hexo | hexo | Hexo 博客框架 | | Jekyll | jekyll | Jekyll 静态站点生成器 | | WordPress | wordpress | WordPress CMS |

📚 API 文档

`migrate(type, options)`

执行迁移操作。

import { migrate, type MigrateOptions } from "@doki-land/doki-migrate";

const result = await migrate("hugo", {
  source: "./content",
  output: "./output",
});

`createMigrator(type)`

创建迁移器实例。

import { createMigrator, BaseMigrator } from "@doki-land/doki-migrate";

const migrator: BaseMigrator = createMigrator("hexo");

`getSupportedMigrators()`

获取所有支持的迁移器类型。

import { getSupportedMigrators } from "@doki-land/doki-migrate";

console.log(getSupportedMigrators()); // ["hugo", "hexo", "jekyll", "wordpress"]

📝 Frontmatter 处理

格式检测与转换

import {
  detectFrontmatterFormat,
  convertFrontmatter,
  parseFrontmatter,
  toFrontmatter,
  type FrontmatterFormat,
} from "@doki-land/doki-migrate";

const content = `---
title: Hello World
date: 2024-01-01
---

Content here...`;

// 检测格式
const format = detectFrontmatterFormat(content); // "yaml"

// 解析 Frontmatter
const parsed = parseFrontmatter(content);
console.log(parsed.data); // { title: "Hello World", date: "2024-01-01" }

// 转换格式
const toml = toFrontmatter(parsed.data, "toml");

支持的 Frontmatter 格式

| 格式 | 标识符 | 定界符 | |------|--------|--------| | YAML | yaml | --- | | TOML | toml | +++ | | JSON | json | { } |

Frontmatter API

// 解析不同格式
import {
  parseYamlFrontmatter,
  parseTomlFrontmatter,
  parseJsonFrontmatter,
} from "@doki-land/doki-migrate";

const yaml = parseYamlFrontmatter(yamlContent);
const toml = parseTomlFrontmatter(tomlContent);
const json = parseJsonFrontmatter(jsonContent);

// 生成不同格式
import {
  toYamlFrontmatter,
  toTomlFrontmatter,
  toJsonFrontmatter,
} from "@doki-land/doki-migrate";

const yamlStr = toYamlFrontmatter(data);
const tomlStr = toTomlFrontmatter(data);
const jsonStr = toJsonFrontmatter(data);

合并与规范化

import {
  mergeFrontmatter,
  normalizeFrontmatter,
} from "@doki-land/doki-migrate";

// 合并 Frontmatter
const merged = mergeFrontmatter(existingData, newData);

// 规范化字段名
const normalized = normalizeFrontmatter(data, {
  title: "title",
  date: "date",
  tags: "tags",
  categories: "categories",
});

🎨 模板转换

import {
  convertTemplate,
  convertHugoTemplate,
  convertHexoTemplate,
  convertJekyllTemplate,
  type TemplateEngine,
} from "@doki-land/doki-migrate";

// 转换 Hugo 模板
const dokiTemplate = convertHugoTemplate(hugoTemplate);

// 通用转换函数
const result = convertTemplate(template, "hugo");

模板语法对照

| 功能 | Hugo | Doki | |------|------|------| | 变量输出 | {{ .Title }} | {{ title }} | | 条件判断 | {{ if .Condition }} | {% if condition %} | | 循环 | {{ range .Items }} | {% for item in items %} | | 模板继承 | {{ block "main" . }} | {% block main %} | | 包含模板 | {{ partial "header" . }} | {% include "header" %} |

📁 迁移结果

interface MigrateResult {
  files: FileMigrateResult[];
  errors: Error[];
  warnings: string[];
}

interface FileMigrateResult {
  source: string;
  output: string;
  success: boolean;
  frontmatterConverted: boolean;
  templateConverted: boolean;
}

🔧 迁移器详情

Hugo 迁移器

import { HugoMigrator } from "@doki-land/doki-migrate";

const migrator = new HugoMigrator();

// Hugo 特有功能
// - 转换 .Params 自定义字段
// - 转换 shortcodes
// - 转换 taxonomies
// - 转换 menus

Hexo 迁移器

import { HexoMigrator } from "@doki-land/doki-migrate";

const migrator = new HexoMigrator();

// Hexo 特有功能
// - 转换 tags/categories
// - 转换 _config.yml 配置
// - 转换 hexo helpers

Jekyll 迁移器

import { JekyllMigrator } from "@doki-land/doki-migrate";

const migrator = new JekyllMigrator();

// Jekyll 特有功能
// - 转换 Liquid 模板
// - 转换 _posts 目录结构
// - 转换 _config.yml 配置

WordPress 迁移器

import { WordPressMigrator } from "@doki-land/doki-migrate";

const migrator = new WordPressMigrator();

// WordPress 特有功能
// - 导出文章和页面
// - 转换分类和标签
// - 下载媒体文件
// - 转换短代码

📝 类型定义

type MigratorType = "hugo" | "hexo" | "jekyll" | "wordpress";
type FrontmatterFormat = "yaml" | "toml" | "json";

interface MigrateOptions {
  source: string;
  output: string;
  convertFrontmatter?: boolean;
  convertTemplates?: boolean;
  frontmatterFormat?: FrontmatterFormat;
}

interface MigrateResult {
  files: FileMigrateResult[];
  errors: Error[];
  warnings: string[];
}

interface ParsedFrontmatter {
  data: Record<string, unknown>;
  content: string;
  format: FrontmatterFormat;
}