跳转到导航 跳转到主要内容
头条
W3C技术联盟，2024 年回顾
CNB版本
社区版
cnb.cool
国外版
cnb.build
2025/12/30

配置

本页大纲

配置文件是可选的。在项目的根目录中添加一个 eleventy.config.js 文件（阅读更多关于 默认配置文件名 的信息）来根据你自己项目的需要配置 W3C技术联盟。它可能看起来像这样：

eleventy.config.js
ESM CommonJS 
export default async function(eleventyConfig) {
// 配置 W3C技术联盟
};
module.exports = async function(eleventyConfig) {
// 配置 W3C技术联盟
};

有几种不同的方式来 构建你的配置文件。(v3.0.0-alpha.1)Eleventy v3 添加了对 ESM 和异步回调的支持。

你的配置文件变得很大且难以理解吗？你可以 创建一个项目特定的插件 来更好地组织你的代码。

默认文件名

我们查找以下配置文件：

  1. .eleventy.js
  2. eleventy.config.js (v2.0.0-canary.15)
  3. eleventy.config.mjs (v3.0.0-alpha.1)
  4. eleventy.config.cjs (v2.0.0-canary.15)

找到的第一个配置文件将被使用。其他的将被忽略。

Play Video: Additions to the default config filename list (Changelog №17) Additions to the default config filename list (Changelog №17) ▶7m11s

配置选项

输入目录

控制我们用来查找模板的顶级目录/文件/glob。

Input Directory
Object Key dir.input
Default Value . (current directory)
Valid Options Any valid directory.
Configuration API eleventyConfig.setInputDirectory() (v3.0.0-alpha.6)
Command Line Override --input

命令行

# 当前目录

npx @11ty/eleventy --input=.

# 单个文件

npx @11ty/eleventy --input=README.md

# 文件 glob

npx @11ty/eleventy --input=\*.md

# 子目录

npx @11ty/eleventy --input=views

Configuration

Via named export (order doesn't matter). Note that there are many different shapes of configuration file.

eleventy.config.js
export const config = {
  dir: {
    input: "views"
  }
};
module.exports.config = {
  dir: {
    input: "views"
  }
};

Or via method (not available in plugins) (v3.0.0-alpha.6):

eleventy.config.js
export default function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
eleventyConfig.setInputDirectory("views");
};
module.exports = function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
eleventyConfig.setInputDirectory("views");
};

Directory for Includes

Includes 目录用于存放 Eleventy 布局、包含文件、扩展文件、部分文件或宏。这些文件不会作为完整模板文件处理，但可以被其他模板使用。

Includes Directory
对象键 dir.includes
默认值 _includes
有效选项 dir.input 内的任何有效目录（支持空字符串 ""）
配置 API eleventyConfig.setIncludesDirectory() (v3.0.0-alpha.6)
命令行覆盖 无

Via named export (order doesn't matter). Note that there are many different shapes of configuration file.

eleventy.config.js
export const config = {
  dir: {
		// ⚠️ 此值相对于你的输入目录。
    includes: "my_includes"
  }
};
module.exports.config = {
  dir: {
		// ⚠️ 此值相对于你的输入目录。
    includes: "my_includes"
  }
};

Or via method (not available in plugins) (v3.0.0-alpha.6):

eleventy.config.js
export default function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
// This is relative to your input directory!
eleventyConfig.setIncludesDirectory("my_includes");
};
module.exports = function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
// This is relative to your input directory!
eleventyConfig.setIncludesDirectory("my_includes");
};

Directory for Layouts (Optional) (v0.8.0)

此配置选项是可选的，但如果您希望 Eleventy 布局 位于 Includes 目录 之外，则非常有用。与 Includes 目录 一样，这些文件不会作为完整模板文件处理，但可以被其他模板使用。

WARNING

此设置仅适用于 Eleventy 与语言无关的布局（在前置元数据或数据文件中定义时）。

使用 {% extends %} 时，Eleventy 将仍然搜索 _includes 目录。

Includes Directory
对象键 dir.layouts
默认值 dir.includes 中的值
有效选项 dir.input 内的任何有效目录（支持空字符串 ""）
配置 API eleventyConfig.setLayoutsDirectory() (v3.0.0-alpha.6)
命令行覆盖 无

Via named export (order doesn't matter). Note that there are many different shapes of configuration file.

eleventy.config.js
export const config = {
  dir: {
    // 这两个都相对于你的输入目录！
    includes: "_includes",
    layouts: "_layouts",
  }
};
module.exports.config = {
  dir: {
    // 这两个都相对于你的输入目录！
    includes: "_includes",
    layouts: "_layouts",
  }
};

Or via method (not available in plugins) (v3.0.0-alpha.6):

eleventy.config.js
export default function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
// This is relative to your input directory!
eleventyConfig.setLayoutsDirectory("\_layouts");
};
module.exports = function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
// This is relative to your input directory!
eleventyConfig.setLayoutsDirectory("\_layouts");
};

Directory for Global Data Files

控制存放全局数据模板文件的目录，这些文件可供所有模板使用。阅读更多关于 全局数据文件 的信息。

Data Files Directory
对象键 dir.data
默认值 _data
有效选项 dir.input 内的任何有效目录
配置 API eleventyConfig.setDataDirectory() (v3.0.0-alpha.6)
命令行覆盖 无

Via named export (order doesn't matter). Note that there are many different shapes of configuration file.

eleventy.config.js
export const config = {
  dir: {
    // ⚠️ 此值相对于你的输入目录。
    data: "lore",
  }
};
module.exports.config = {
  dir: {
    // ⚠️ 此值相对于你的输入目录。
    data: "lore",
  }
};

Or via method (not available in plugins) (v3.0.0-alpha.6):

eleventy.config.js
export default function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
eleventyConfig.setDataDirectory("lore");
};
module.exports = function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
eleventyConfig.setDataDirectory("lore");
};

Output Directory

控制将完成的模板写入到哪个目录。

Output Directory
对象键 dir.output
默认值 _site
有效选项 任何可以作为目录名称的字符串。如果不存在，Eleventy 会创建它。
配置 API eleventyConfig.setOutputDirectory() (v3.0.0-alpha.6)
命令行覆盖 --output

命令行

npx @11ty/eleventy --output=_site

配置

Via named export (order doesn't matter). Note that there are many different shapes of configuration file.

eleventy.config.js
export const config = {
  dir: {
		output: "dist",
  }
};
module.exports.config = {
  dir: {
		output: "dist",
  }
};

Or via method (not available in plugins) (v3.0.0-alpha.6):

eleventy.config.js
export default function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
eleventyConfig.setOutputDirectory("dist");
};
module.exports = function(eleventyConfig) {
// Order matters, put this at the top of your configuration file.
eleventyConfig.setOutputDirectory("dist");
};

Markdown 文件的默认模板引擎

Markdown 文件在转换为 HTML 之前会通过此模板引擎处理。

Markdown Template Engine
对象键 markdownTemplateEngine
默认值 liquid
有效选项 有效的 模板引擎简称 或 false
命令行覆盖 无
配置 API setMarkdownTemplateEngine (v4.0.0-alpha.1)
eleventy.config.js
export const config = {
  markdownTemplateEngine: "njk",
};
module.exports.config = {
  markdownTemplateEngine: "njk",
};
 有许多[不同形式的配置文件](/docs/config-shapes.md)。

HTML 文件的默认模板引擎

HTML 模板在转换为（更好的）HTML 之前会通过此模板引擎处理。

HTML Template Engine
对象键 htmlTemplateEngine
默认值 liquid
有效选项 有效的 模板引擎简称 或 false
命令行覆盖 无
配置 API setHtmlTemplateEngine (v4.0.0-alpha.1)
eleventy.config.js
export const config = {
  htmlTemplateEngine: "njk",
};
module.exports.config = {
  htmlTemplateEngine: "njk",
};
 There are many [different shapes of configuration file](/docs/config-shapes.md).

Template Formats

指定应该转换哪些类型的模板。

Template Formats
对象键 templateFormats
默认值 html,liquid,ejs,md,hbs,mustache,haml,pug,njk,11ty.js
有效选项 模板引擎简称 数组
命令行覆盖 --formats （接受逗号分隔的字符串）
配置 API setTemplateFormats (v0.2.14) 和 addTemplateFormats (v0.11.0)
(v0.9.0) Case sensitivity: File extensions should be considered case insensitive, cross-platform. While macOS already behaves this way (by default), other operating systems require additional Eleventy code to enable this behavior.

Command Line

npx @11ty/eleventy --formats=html,liquid,njk

Configuration File Static Export

eleventy.config.js
export const config = {
  templateFormats: ["html", "liquid", "njk"],
};
module.exports.config = {
  templateFormats: ["html", "liquid", "njk"],
};

There are many different shapes of configuration file.

Configuration API

eleventy.config.js
export default function (eleventyConfig) {
// Reset to this value
eleventyConfig.setTemplateFormats("html,liquid,njk");

    // Additive to existing
    eleventyConfig.addTemplateFormats("pug,haml");

    // Or:
    // eleventyConfig.setTemplateFormats([ "html", "liquid", "njk" ]);
    // eleventyConfig.addTemplateFormats([ "pug", "haml" ]);

};
module.exports = function (eleventyConfig) {
// Reset to this value
eleventyConfig.setTemplateFormats("html,liquid,njk");

    // Additive to existing
    eleventyConfig.addTemplateFormats("pug,haml");

    // Or:
    // eleventyConfig.setTemplateFormats([ "html", "liquid", "njk" ]);
    // eleventyConfig.addTemplateFormats([ "pug", "haml" ]);

};

Enable Quiet Mode to Reduce Console Noise

为了最大限度地提高对初学者的友好性，Eleventy 会显示它处理的每个文件和输出文件。要禁用这种嘈杂的控制台输出，请使用静默模式！

Quiet Mode
默认值 false
有效选项 true 或 false
命令行覆盖 --quiet
eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.setQuietMode(true);
};
module.exports = function (eleventyConfig) {
eleventyConfig.setQuietMode(true);
};

命令行将覆盖配置中的任何设置：

npx @11ty/eleventy --quiet

Deploy to a subdirectory with a Path Prefix

如果您的站点位于不同的子目录中（对于 GitHub pages 特别有用），请使用 pathPrefix 来指定此目录。当与 HTML <base> 插件 配合使用时，它将转换 HTML 中的任何绝对 URL 以包含此文件夹名称，并且不会影响内容在输出文件夹中的位置。

Path Prefix
对象键 pathPrefix
默认值 /
有效选项 添加到 HTML 文件中 URL 的前缀目录
命令行覆盖 --pathprefix (v0.2.11)
eleventy.config.js
import { HtmlBasePlugin } from "@11ty/eleventy";
export default function (eleventyConfig) {
	eleventyConfig.addPlugin(HtmlBasePlugin);
};
export const config = {
	pathPrefix: "/eleventy-base-blog/",
}
module.exports = async function (eleventyConfig) {
	const { HtmlBasePlugin } = await import("@11ty/eleventy");

	eleventyConfig.addPlugin(HtmlBasePlugin);
};

module.exports.config = {
	pathPrefix: "/eleventy-base-blog/",
}

无需修改配置即可部署到 https://blog.w3c.cool/eleventy-base-blog/。这允许您使用相同的代码库部署到不同平台，就像 eleventy-base-blog 项目那样。

npx @11ty/eleventy --pathprefix=eleventy-base-blog

Change Base File Name for Data Files

(v2.0.0-canary.19) 使用 目录特定数据文件 时，会查找与当前文件夹名称匹配的数据文件。您可以使用 setDataFileBaseName 方法将此行为覆盖为静态字符串。

File Suffix
Configuration API setDataFileBaseName
Default Current folder name
Valid Options String
Command Line Override None
eleventy.config.js
export default function (eleventyConfig) {
// Looks for index.json and index.11tydata.json instead of using folder names
eleventyConfig.setDataFileBaseName("index");
};
module.exports = function (eleventyConfig) {
// Looks for index.json and index.11tydata.json instead of using folder names
eleventyConfig.setDataFileBaseName("index");
};

Change File Suffix for Data Files

(v2.0.0-canary.19) 使用 模板和目录特定数据文件 时，为了防止与项目目录中的非 Eleventy 文件发生文件名冲突，我们使用 Eleventy 独有的后缀来限定这些文件。此后缀可以使用 setDataFileSuffixes 配置 API 方法进行自定义。

File Suffix
Configuration API setDataFileSuffixes
Default [".11tydata", ""]
Valid Options Array
Command Line Override None

例如，使用 ".11tydata" 将搜索 *.11tydata.js 和 *.11tydata.json 数据文件。这里的空字符串（""）表示没有后缀的文件——此条目仅适用于 *.json 数据文件。

此功能也可用于通过空数组（[]）完全禁用模板和目录数据文件。

阅读更多关于 模板和目录特定数据文件 的信息。

eleventy.config.js
export default function (eleventyConfig) {
// e.g. file.json and file.11tydata.json
eleventyConfig.setDataFileSuffixes([".11tydata", ""]);

    // e.g. file.11tydata.json
    eleventyConfig.setDataFileSuffixes([".11tydata"]);

    // No data files are used.
    eleventyConfig.setDataFileSuffixes([]);

};
module.exports = function (eleventyConfig) {
// e.g. file.json and file.11tydata.json
eleventyConfig.setDataFileSuffixes([".11tydata", ""]);

    // e.g. file.11tydata.json
    eleventyConfig.setDataFileSuffixes([".11tydata"]);

    // No data files are used.
    eleventyConfig.setDataFileSuffixes([]);

};
Backwards Compatibility Note (2.0.0)

在 2.0.0 之前，此功能通过配置返回对象中的 jsDataFileSuffix 属性暴露。当 setDataFileSuffixes 方法未被使用时，Eleventy 通过使用此属性作为后备来维护对旧项目的向后兼容性。

eleventy.config.js
export default function (eleventyConfig) {
return {
jsDataFileSuffix: ".11tydata",
};
};
module.exports = function (eleventyConfig) {
return {
jsDataFileSuffix: ".11tydata",
};
};

Transforms

Linters

与 Transforms 类似，Linters 用于分析模板的输出而不修改它。

Linters
Configuration API addLinter
Object Key N/A
Valid Options Callback function
Command Line Override None
eleventy.config.js
export default function (eleventyConfig) {
// Sync or async
eleventyConfig.addLinter("linter-name", async function (content) {
console.log(this.inputPath);
console.log(this.outputPath);

    	// Eleventy 2.0+ has full access to Eleventy's `page` variable
    	console.log(this.page.inputPath);
    	console.log(this.page.outputPath);
    });

};
module.exports = function (eleventyConfig) {
// Sync or async
eleventyConfig.addLinter("linter-name", async function (content) {
console.log(this.inputPath);
console.log(this.outputPath);

    	// Eleventy 2.0+ has full access to Eleventy's `page` variable
    	console.log(this.page.inputPath);
    	console.log(this.page.outputPath);
    });

};
Linters Example: Use Inclusive Language

Inspired by the CSS Tricks post Words to Avoid in Educational Writing, this linter will log a warning to the console when it finds a trigger word in a markdown file.

This example has been packaged as a plugin in eleventy-plugin-inclusive-language.

Filename eleventy.config.js
export default function (eleventyConfig) {
	eleventyConfig.addLinter(
		"inclusive-language",
		function (content, inputPath, outputPath) {
			let words =
				"simply,obviously,basically,of course,clearly,just,everyone knows,however,easy".split(
					",",
				)

			// Eleventy 1.0+: use this.inputPath and this.outputPath instead
			if (inputPath.endsWith(".md")) {
				for (let word of words) {
					let regexp = new RegExp("\\b(" + word + ")\\b", "gi")
					if (content.match(regexp)) {
						console.warn(
							`Inclusive Language Linter (${inputPath}) Found: ${word}`,
						)
					}
				}
			}
		},
	)
}

Data Filter Selectors

(v1.0.0)

一组 lodash 选择器，允许您在 --to=json、--to=ndjson 的输出中包含来自数据级联的数据。

eleventy.config.js
export default function (eleventyConfig) {
eleventyConfig.dataFilterSelectors.add("page");
eleventyConfig.dataFilterSelectors.delete("page");
};
module.exports = function (eleventyConfig) {
eleventyConfig.dataFilterSelectors.add("page");
eleventyConfig.dataFilterSelectors.delete("page");
};

这现在将在您的 JSON 输出中包含一个 data 属性，其中包括每个匹配模板的 page 变量。

TypeScript Type Definitions

这可能在您的 IDE 中启用一些额外的自动完成功能（在支持的 IDE 中）。

eleventy.config.js
export default function (eleventyConfig) {
// …
};
module.exports = function (eleventyConfig) {
// …
};

Removed Features

Change exception case suffix for HTML files

Feature Removal
The htmlOutputSuffix feature was removed in Eleventy 3.0. You can read about the feature on the v2 documentation. Related: Issue #3327.

Documentation Moved to Dedicated Pages

Copy Files to Output using Passthrough File Copy

Files found (that don't have a valid template engine) from opt-in file extensions in templateFormats will passthrough to the output directory. Read more about Passthrough Copy.

Customize Front Matter Parsing Options (v0.9.0)

Watch JavaScript Dependencies (v0.7.0)

Add Your Own Watch Targets (v0.10.0)

Override Browsersync Server Options (v0.7.0)

Transforms

其他页面在 Eleventy Projects