将您的 WordPress 站点导入到 Publish。

• 简介
  • 要求
  • 安装
  • 工作原理
  • 从 WordPress 导出
• 用法
  • 入门
  • 导出到 Publish
  • 从活动站点下载资源
  • 从本地备份复制资源
  • 将文章转换为 Markdown
  • 使用 ShellOut 和 Pandoc 生成 Markdown
  • 过滤文章
  • 重定向旧 URL
  • 使用 SwiftArgumentParser 进行设置
  • 更多文档
• 许可证

ContributeWordPress 提供了一个易于使用的 API，用于将 WordPress 站点导入到 Publish。

Apple 平台

• Xcode 14.3.1 或更高版本
• Swift 5.8 或更高版本
• macOS 12 或更高版本部署目标

Linux

• Ubuntu 18.04 或更高版本
• Swift 5.8 或更高版本

使用 Swift Package Manager 通过存储库 URL 安装此库

https://github.com/brightdigit/ContributeWordPress.git

使用最高版本 1.0.0。

ContributeWordPress 使用导出的 XML 文件（也称为 WXR 文件）将内容导入到您现有的 Publish 站点。

import ContributeWordPress

let fromURL = URL(
    fileURLWithPath: "directory/containing/your/export/xml/files"
)
let toURL = URL(
    fileURLWithPath: "Path/to/Publish/root"
)

try MarkdownProcessor.beginImport(
    from: fromURL, 
    to: toURL
)

为了开始，您需要

• 导出的 XML 文件
• 活动的 WordPress 站点或站点的完整文件下载（用于您站点上的图像）

ContributeWordPress 需要您 WordPress 站点的备份 XML 文件。要做到这一点

1. 登录到您的 WordPress 管理仪表板。
2. 转到工具...导出：
3. 通过以下方式下载您的导出文件
   • 单击“导出全部”按钮（如果您有一个未安装插件的站点。）
   • 选择所有内容并单击“下载导出文件”按钮（如果您有一个已安装插件的站点。）
   • 仅下载特定内容，例如帖子、页面或反馈。
4. 您将收到一个 .zip 文件，其中包含 .xml 文件并将其保存到您的计算机。此文件包含您的帖子、页面、评论、类别、标签以及对您站点图像的引用。

较大的站点将包含多个 XML 文件，以确保您的导出过程快速且成功完成，例如，如果您正在运行多站点 WordPress。幸运的是，ContributeWordPress 支持导入多个 XML 文件！

导入 BrightDigit 网站时，内容被导入到 brightdigit.com/tutorials 中 Learningswift.brightdigit.com，brightdigit.com 被导入到 brightdigit.com/articles 中。

有关导出过程的更多详细信息，请阅读 WordPress 站点上的文档。

除了导出您的 WordPress 站点，您还需要通过以下方式访问图像

• 直接从站点下载
• 拥有站点文件的副本

获得这两个组件后，您需要设置一个 Publish 站点。网上有很多很棒的教程

• JohnSundell/Publish: Swift 开发人员的静态站点生成器
• 如何使用 Publish 在 Swift 中创建个人网站 | Danijela 的博客
• 使用 Publish、Plot 和 Ink 通过 Swift 进行静态站点生成
• 使用 Publish 在 Swift 中开始使用静态站点生成 | Andy Regensky

站点设置完成后，我们可以

• 将导出的 XML（也称为 WXR 文件）中的 HTML 转换并翻译到 Content 目录中的 Markdown 文件
• 将 WordPress 上传文件夹中的图像和其他文件下载（或复制）到 Resources 目录

导入您的 WordPress 站点最简单的方法是只传递您的 xml 文件以及您的 Publish 站点的根目录的路径。

import ContributeWordPress

let fromURL = URL(
    fileURLWithPath: "directory/containing/your/export/xml/files"
)
let toURL = URL(
    fileURLWithPath: "Path/to/Publish/root"
)

try MarkdownProcessor.beginImport(
    from: fromURL, 
    to: toURL
)

如果您希望创建一个小的命令行应用程序，您可以接受这两个路径的命令行参数

import ContributeWordPress

let fromURL : URL
let toURL : URL

guard CommandLine.arguments.count == 2 else {
  exit(1)
}

fromURL = .init(fileURLWithPath: CommandLine.arguments[0])
toURL = .init(fileURLWithPath: CommandLine.arguments[1])

try! MarkdownProcessor.beginImport(from: fromURL, to: toURL)

默认情况下，ContributeWordPress 将从您活动的 WordPress 站点下载图像。 因此，如果它遇到对您站点的 URL 的引用，它会将 URL 更改为将要导入的新地址。

因此，您的导出文件中的 HTML 将从

<figure class="wp-block-image"><img src="https://leogdion.name/wp-content/uploads/2019/01/image-e1547230562842-1024x682.jpg" alt="A JavaScript Meetup I hosted in 2018 " class="wp-image-105"/><figcaption>A JavaScript Meetup I hosted in 2018 </figcaption></figure>

变为 Markdown 文件中的这个

<figure class="wp-block-image">
<img
src="/media/wp-assets/default/2019/01/image-e1547230562842-1024x682.jpg"
class="wp-image-105" alt="A JavaScript Meetup I hosted in 2018 " />
<figcaption>A JavaScript Meetup I hosted in 2018</figcaption>
</figure>

如果您的站点不再活动，但您拥有站点的本地副本，则可以传入该目录以代替使用。

让我们通过添加一个可选参数来扩展我们之前的命令行示例

let fromURL : URL
let toURL : URL

let importAssetsSetting : AssetImportSetting

guard CommandLine.arguments.count >= 2 else {
  exit(1)
}

fromURL = URL(fileURLWithPath: CommandLine.arguments[0])
toURL = URL(fileURLWithPath: CommandLine.arguments[1])

// if a third argument is passed
if CommandLine.arguments.count > 2 {
  // assume they want to copy the resources directly
  importAssetsSetting = .copyFilesFrom(
    URL(fileURLWithPath: CommandLine.arguments[2])
  )
} else {
  // otherwise use the default `download` option
  importAssetsSetting = .download
}

try! MarkdownProcessor.beginImport(
  from: fromURL,
  to: toURL,
  importAssetsBy: importAssetsSetting
)

因此您可以调用

> wpublish \
  directory/with/export/xml/files \
  Path/to/Publish/root \
  path/to/root/wordpress/files

AssetImportSetting 选项包含三个选项

• none - 什么都不做
• download - 从 WordPress 站点下载它们
• copyFilesFrom(URL) - 从本地映射的位置复制文件

默认情况下，ContributeWordPress 不实现任何将 WordPress 文章中的 HTML 转换为 Markdown 的特定方法。

但是，有一些易于使用的实现以及插入您自己的实现的能力。

具体来说，这可以通过将 MarkdownGenerator 传递给处理器来完成

try! MarkdownProcessor.beginImport(
  from: fromURL,
  to: toURL,
  usingGenerator: // your `MarkdownGenerator` here,
  importAssetsBy: importAssetsSetting
)

MarkdownGenerator 是来自 Contribute 基本库的简单协议，它接受 HTML String 并返回新的 markdown String。

/// A protocol for generating Markdown from HTML.
public protocol MarkdownGenerator {
  /// Converts an HTML string to Markdown.
  ///
  /// - Parameter htmlString: The HTML string to convert.
  /// - Returns: The generated Markdown string.
  /// - Throws: An error if the conversion fails.
  func markdown(fromHTML htmlString: String) throws -> String
}

默认情况下，我们使用 PassthroughMarkdownGenerator，它什么也不做。 但是您可以实现自己的或使用 HTMLtoMarkdown 来传入闭包。

如果您希望将 WordPress 文章中的 HTML 转换为 Markdown，建议的解决方案是使用 Contribute 库中包含的 PanddocMarkdownGenerator。 PanddocMarkdownGenerator 需要 ShellOut 库来运行 Pandoc 的安装。

在您的机器上安装 Pandoc 的推荐方法是通过 homebrew

> brew install pandoc

安装 Pandoc 后，您可以运行命令作为使用 ShellOut 导入的一部分。

这是一个使用插入 ShellOut 的简单代码片段

extension PandocMarkdownGenerator {
  public static func defaultShellOut(to command: String, arguments: [String]) throws -> String {
    try ShellOut.shellOut(to: command, arguments: arguments)
  }
  
  public init (temporaryFile: @escaping (String) throws -> URL = Temporary.file(fromContent:)) {
    self.init(shellOut: Self.defaultShellOut(to:arguments:), temporaryFile: temporaryFile)
  }
}

从这里，我们现在可以简单地使用 PandocMarkdownGenerator 将我们的 WordPress HTML 转换为 Markdown

try! MarkdownProcessor.beginImport(
  from: fromURL,
  to: toURL,
  usingGenerator: PandocMarkdownGenerator(),
  importAssetsBy: importAssetsSetting
)

来自 WordPress 的导出文件包含大量信息，包括未发布的帖子以及非帖子项目。 默认情况下，导入仅过滤已发布的帖子。 这些是使用 RegexKeyPostFilter 类型设置的，该类型接收来自 SyndiKit 库的具有 String 类型的 WordPressPost 属性的 KeyPath 和 NSRegularExpression。

这是默认 RegexKeyPostFilter 项目的示例

    [
        RegexKeyPostFilter(pattern: "post", keyPath: \.type),
        RegexKeyPostFilter(pattern: "publish", keyPath: \.status)
    ]

此外，您可以实现您自己的任何类型的 PostFilter 并将其传入

try! MarkdownProcessor.beginImport(
  from: fromURL,
  to: toURL,
  filteringPostsWith: // array of `PostFilter` items
  importAssetsBy: importAssetsSetting
)

如果您要从 WordPress 迁移到 Publish 站点，可能需要将几个旧 URL 重定向到您新站点。 这可以通过传递 RedirectFormatter 来完成。 这需要实现两种方法

• formatRedirects 接收 RedirectItem 对象（即，旧 URL，新 URL）的集合，并期望一个将写入某些位置的字符串。
• redirectsURL(basedOnResourcesDirectoryURL:) 返回需要写入该 String 的文件的 URL。

默认情况下，不导出任何重定向文件，因此如果需要，您需要提供自己的重定向文件。 否则，仅通过 NetlifyRedirectFormatter 支持 Netlify。 如果需要，可以通过 RedirectFileWriter 获得更精细的控制。

欢迎发布问题或拉取请求以获取您自己的实现或问题。

虽然您可能希望使用 CommandLine 对象自己解析参数，但强烈建议您使用 Swift Argument Parser 以获得更复杂的选项。

欢迎查看 此处的示例。

更多文档可在 Swift Package Index 上获得。

此代码根据 MIT 许可证分发。 有关更多信息，请参阅 LICENSE 文件。