迁移到 Lume 2

将你的项目从 Lume 1 迁移到 Lume 2 的指南

本页面是一个简要的待办事项清单，列出了将站点从 Lume 1 迁移到 Lume 2 的主要更改。你可以在公告帖子中找到更详细的描述。

更改你的（预）处理器

在 Lume 2 中，处理器和预处理器接收包含所有页面的数组：

// Lume 1 版本
site.process([".html"], fn);

// Lume 2 版本
site.process([".html"], (pages) => pages.forEach(fn));

// Lume 2 版本 (异步函数)
site.process([".html"], (pages) => Promise.all(pages.map(fn)));

如果你正在使用 (pre)processAll，请将其重命名为 (pre)process：

// Lume 1 版本
site.processAll([".html"], fn);

// Lume 2 版本
site.process([".html"], fn);

更改 `.page.*` 页面

TypeScript/JavaScript 页面的子扩展名 .tmpl 已更改为 .page，并且布局不再需要它。 Lume 1 中的这种结构：

_includes/layout.tmpl.js
_components/button.js
_data.js
index.tmpl.js

在 Lume 2 中变为：

_includes/layout.js
_components/button.js
_data.js
index.page.js

这是一个简单的脚本可以自动重命名文件。要继续使用 .page 作为子扩展名，你可以编辑 module 和 json 插件的 pageSubExtension 选项：

import lume from "lume/mod.ts";

const modules = { pageSubExtension: ".page" };
const json = { pageSubExtension: ".page" };

const site = lume({}, { modules, json });

export default lume;

URL 生成的更改：

`url` 函数

如果你正在使用 url() 函数生成页面的 URL，请记住 page.src.slug 属性已被删除。请改用 page.data.basename。

// Lume 1 版本
export const url = (page) => `/articles/${page.src.slug}/`;

// Lume 2 版本
export const url = (page) => `/articles/${page.data.basename}/`;

在 Lume 2 中，传递给函数的页面已经应用了默认 URL，这更容易进行小的调整：

// 仅在 Lume 2 版本中:
// 仅删除 `/foo/` 目录:

export const url = (page) => page.data.url.replace("/foo/", "/");

404 页面

漂亮的 URL 不再输出 /404/index.html：

# Lume 1 版本
/404.md  => /404/index.html

# Lume 2 版本
/404.md  => /404.html

要恢复此设置，请在 Frontmatter 中使用 url 变量。

自动扩展名检测

在 Lume 2 中，输出扩展名不再从文件名中检测。默认情况下，所有页面都导出为 HTML：

# Lume 1 版本
/styles.css.md  => /styles.css

# Lume 2 版本
/styles.css.md  => /styles.css/index.html

在页面的 Frontmatter 中使用 url 变量来分配其他扩展名。

已删除的标志

如果你正在使用 --quiet 或 --dev 标志来运行 Lume，它们已被环境变量替换：

# Lume 1 版本
deno task lume --dev
deno task lume --quiet

# Lume 2 版本
LUME_DRAFTS=true deno task lume
LUME_LOGS=critical deno task lume

Imagick 插件

imagick 插件已被 transform_images 替换：

// Lume 1 版本
import imagick from "lume/plugins/imagick.ts";

site.use(imagick());

// Lume 2 版本
import transformImages from "lume/plugins/transform_images.ts";

site.use(transformImages());

这两个插件的工作方式类似，但使用的数据键不同：

# Lume 1 版本
imagick:
  - format: webp
    resize: [100, 200]

# Lume 2 版本
transformImages:
  - format: webp
    resize: [100, 200]

Picture 插件

Picture 插件在底层使用了新的 transform_images 插件，因此 HTML 属性名称已更改为 transform-images：

<!-- Lume 1 版本 -->
<img src="/flowers.jpg" imagick="avif jpg 600" />

<!-- Lume 2 版本 -->
<img src="/flowers.jpg" transform-images="avif jpg 600" />

Nunjucks 插件

Lume 1.x 默认启用了 nunjucks 插件。在 Lume 2.x 中，它是一个可选插件。如果你正在使用 Nunjucks 模板，请在你的 _config.ts 文件中导入插件：

import lume from "lume/mod.ts";
import nunjucks from "lume/plugins/nunjucks.ts";

const site = lume();
site.use(nunjucks());

export default site;

Vento 插件

此插件默认启用。如果你正在使用此模板引擎，请删除 _config 文件中的导入。

搜索

函数 search.page() 和 search.pages() 返回数据对象而不是页面实例：

// Lume 1 版本
for (const page of search.pages("type=article")) {
  <h1>{page.data.title}</h1>;
}

// Lume 2 版本
for (const data of search.pages("type=article")) {
  <h1>{data.title}</h1>;
}

函数 search.tags() 已被删除。使用 search.values：

// Lume 1 版本
const tags = search.tags();

// Lume 2 版本
const tags = search.values("tags");

过滤器 data 已被删除：

<!-- Lume 1 版本 -->
{% for article in search.pages("type=article") | data %}

<!-- Lume 2 版本 -->
{% for article in search.pages("type=article") %}

JSX 插件

全局对象 window.React 已被删除。如果你在编译 JSX 页面时遇到问题，请在 deno.json 文件中配置 JSX 转换器：

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "npm:react",
    "types": [
      "https://unpkg.com/@types/react@18.2.37/index.d.ts"
    ]
  }
}

Slugify URLs 插件

如果你正在使用 slugify_urls 插件，它还会 slugify 使用 site.copy() 复制的文件。要禁用它：

site.use(slugifyUrls({
  extensions: [".html"], // 仅 slugify HTML 页面
}));

Netlify CMS 插件

此插件已重命名为 decap_cms。并且 netlifyIdentity 选项已重命名为 identity：

// Lume 1 版本
site.use(netlifyCMS({
  netlifyIdentity: true,
}));

// Lume 2 版本
site.use(decapCMS({
  identity: "netlify",
}));

WindiCSS 插件

此插件已被 UnoCSS 替换：

// Lume 1 版本
site.use(windiCSS());

// Lume 2 版本
site.use(unoCSS());

UnoCSS 插件不是 windiCSS 的 1:1 替代品。此链接中有比较

Feed 插件

以下选项已被重命名：

// Lume 1 版本
site.use(feed({
  info: {
    date: "=date",
  },
  item: {
    date: "=date",
  },
}));

// Lume 2 版本
site.use(feed({
  info: {
    updated: "=date",
  },
  item: {
    updated: "=date",
    published: "=date", // 新选项!
  },
}));

Multilanguage 插件

multilanguage 插件不再允许使用 .[lang] 前缀进行翻译：

# Lume 1 版本
title: Default title
title.gl: Translation to galician
title.es: Translation to spanish

description: Default description
description.gl: Translation to galician
description.es: Translation to spanish

# Lume 2 版本
title: Default title
description: Default description

gl:
  title: Translation to galician
  description: Translation to galician

es:
  title: Translation to spanish
  description: Translation to spanish

插件选项

选项 keepDefaultPlugins 已重命名为 useDefaultPlugins，默认值为 true。这会影响 postcss、markdown、mdx、remark 插件。

// Lume 1 版本
import reporter from "npm:postcss-reporter";

site.use(postcss({
  plugins: [reporter],
  keepDefaultPlugins: true,
}));

// Lume 2 版本
import reporter from "npm:postcss-reporter";

site.use(postcss({
  plugins: [reporter],
}));

TypeScript

已删除 /lume/core.ts。在 deno.json 文件中导入 Lume 命名空间：

{
  // ...
  "compilerOptions": {
    "types": [
      "lume/types.ts"
    ]
  }
}

在 Lume 1 中：

import { PageData, PageHelpers } from "lume/core.ts";

export default function (data: PageData, helpers: PageHelpers) {
  return `<h1>${data.title}</h1>`;
}

在 Lume 2 中：

export default function (data: Lume.Data, helpers: Lume.Helpers) {
  return `<h1>${data.title}</h1>`;
}