Menu
5.81s
14.77s
配置
Contents
- 配置文件的默认名称
- 配置参数
- Input 目录
- Includes 目录
- 用于存放布局文件(layout)的目录(可选)
- 全局数据文件所在目录
- Output Directory
- 全局数据文件的默认预处理引擎
- Markdown 文件的默认预处理引擎
- HTML 文件的默认预处理引擎
- Template Formats
- Enable Quiet Mode to Reduce Console Noise
- Deploy to a subdirectory with a Path Prefix
- Change exception case suffix for HTML files
- Change Base File Name for Data Files
- Change File Suffix for Data Files
- Transforms
- Linters
- Data Filter Selectors
- Type Definitions
- Documentation Moved to Dedicated Pages
配置文件不是必须的。如果你的项目需要的话,可以添加名为 .eleventy.js
的配置文件到项目的根目录下。大概类似下面这样:
module.exports = function(eleventyConfig) {
// Return your Object options:
return {
dir: {
input: "views",
output: "dist"
}
}
};
Eleventy 支持We support returning both a callback function (shown above) or an object literal (module.exports = {}
). Callback functions are preferred and allow you further customization options using Eleventy’s provided helper methods.
- Add Filters.
- Add Shortcodes.
- Add Custom Tags.
- Add JavaScript Functions
- Add custom Collections and use Advanced Collection Filtering and Sorting.
- Add some Plugins.
配置文件的默认名称 Jump to heading
Eleventy 会依次查找具有如下名称的文件作为配置文件:
.eleventy.js
eleventy.config.js
Added in v2.0.0eleventy.config.cjs
Added in v2.0.0
第一个被找到的配置文件将被使用,其它均被忽略。
配置参数 Jump to heading
Input 目录 Jump to heading
用于存放模板文件的根目录。
Input Directory | |
---|---|
Object Key | dir.input |
默认值 | . (当前目录) |
有效值 | 任何有效的目录。 |
命令行参数 | --input |
示例 Jump to heading
命令行用法
# 当前目录
npx @11ty/eleventy --input=.
# 单个文件
npx @11ty/eleventy --input=README.md
# 用 glob 模式匹配的所有文件
npx @11ty/eleventy --input=*.md
# 当前目录下的某个子目录
npx @11ty/eleventy --input=views
配置
module.exports = function(eleventyConfig) {
return {
dir: {
input: "views"
}
}
};
Includes 目录 Jump to heading
Includes 目录用于存放 Eleventy 的布局文件(layout), include files, extends files, partials, or macros. These files will not be processed as full template files, but can be consumed by other templates.
Includes 目录 | |
---|---|
Object Key | dir.includes |
默认值 | _includes |
有效值 | Any valid directory inside of dir.input (an empty string "" is supported) |
命令行参数 | 无 |
示例 Jump to heading
module.exports = function(eleventyConfig) {
return {
dir: {
// ⚠️ 此目录是 input 目录的子目录
includes: "my_includes"
}
}
};
用于存放布局文件(layout)的目录(可选) Jump to heading
此配置项是可选的,但是,如果你希望将 Eleventy 的布局文件(layouts) 存放在 Includes 目录 之外,则此配置项非常有用。就像 Includes 目录 一样,这些文件不会被当作完整的模板文件处理,但可以由其它模板文件使用。
此设置 仅适用于 Eleventy 所支持的与模板语言无关的 布局文件(layouts) (when defined in front matter or data files).
当使用 {% extends %}
指令时,Eleventy 仍将 搜索 _includes
目录。参见 这份关于模板现有功能的说明。
Includes Directory | |
---|---|
Object Key | dir.layouts |
默认值 | dir.includes 的值 |
有效值 | 任何 dir.input 目录下的有效目录 (空字符串 "" 也可以) |
命令行参数 | 无 |
示例 Jump to heading
module.exports = function(eleventyConfig) {
return {
dir: {
// ⚠️ 以下设置的目录都是 Input 目录下的子目录。
includes: "_includes",
layouts: "_layouts"
}
}
};
全局数据文件所在目录 Jump to heading
此目录存放的是可以被所有模板所使用的全局数据文件的存放目录。更多信息请参考 全局数据文件(Global Data Files)。
全局数据文件 | |
---|---|
Object Key | dir.data |
默认值 | _data |
有效值 | dir.input 目录下的任何有效的子目录 |
命令行参数 | 无 |
示例 Jump to heading
module.exports = function(eleventyConfig) {
return {
dir: {
// ⚠️ 以下目录是 Input 目录下的子目录。
data: "lore"
}
}
};
Output Directory Jump to heading
Controls the directory inside which the finished templates will be written to.
Output Directory | |
---|---|
Object Key | dir.output |
默认值 | _site |
有效值 | Any string that will work as a directory name. Eleventy creates this if it doesn’t exist. |
命令行参数 | --output |
示例 Jump to heading
module.exports = function(eleventyConfig) {
return {
dir: {
output: "dist"
}
}
};
全局数据文件的默认预处理引擎 Jump to heading
Markdown 文件的默认预处理引擎 Jump to heading
Markdown 文件在被转换为 HTML 之前会经过此处设置的模板引擎进行预处理。
Markdown 文件的默认预处理引擎 | |
---|---|
Object Key | markdownTemplateEngine |
默认值 | liquid |
有效值 | 有效的 模板引擎简称 或 false |
命令行参数 | 无 |
示例 Jump to heading
module.exports = function(eleventyConfig) {
return {
markdownTemplateEngine: "njk"
}
};
HTML 文件的默认预处理引擎 Jump to heading
HTML 文件在被转换为(更好的) HTML 之前会经过此处设置的模板引擎进行预处理。
HTML 文件的默认预处理引擎 | |
---|---|
Object Key | htmlTemplateEngine |
默认值 | liquid |
有效值 | 有效的 模板引擎简称 或 false |
命令行参数 | 无 |
示例 Jump to heading
module.exports = function(eleventyConfig) {
return {
htmlTemplateEngine: "njk"
}
};
Template Formats Jump to heading
Specify which types of templates should be transformed.
Template Formats | |
---|---|
Object Key | templateFormats |
Default | html,liquid,ejs,md,hbs,mustache,haml,pug,njk,11ty.js |
Valid Options | Array of template engine short names |
Command Line Override | --formats (accepts a comma separated string) |
Configuration API | setTemplateFormats |
Examples Jump to heading
module.exports = function(eleventyConfig) {
return {
templateFormats: ["html", "liquid", "njk"]
}
};
module.exports = function(eleventyConfig) {
eleventyConfig.setTemplateFormats("html,liquid,njk");
// Or:
// eleventyConfig.setTemplateFormats([ "html", "liquid", "njk" ]);
};
npx @11ty/eleventy --formats=html,liquid,njk
Enable Quiet Mode to Reduce Console Noise Jump to heading
In order to maximize user-friendliness to beginners, Eleventy will show each file it processes and the output file. To disable this noisy console output, use quiet mode!
Quiet Mode | |
---|---|
Default | false |
Valid Options | true or false |
Command Line Override | --quiet |
Example Jump to heading
module.exports = function(eleventyConfig) {
eleventyConfig.setQuietMode(true);
};
The command line will override any setting in configuration:
npx @11ty/eleventy --quiet
Deploy to a subdirectory with a Path Prefix Jump to heading
If your site lives in a different subdirectory (particularly useful with GitHub pages), use pathPrefix to specify this. It’s used by the url
filter and inserted at the beginning of all absolute url href links. It does not affect your file structure. Leading or trailing slashes are all normalized away, so don’t worry about it.
Path Prefix | |
---|---|
Object Key | pathPrefix |
Default | / |
Valid Options | A prefix directory added to links |
Command Line Override | --pathprefix |
Example Jump to heading
module.exports = function(eleventyConfig) {
return {
pathPrefix: "/eleventy-base-blog/"
}
};
Deploy to https://11ty.github.io/eleventy-base-blog/ on GitHub pages without modifying your config. This allows you to use the same code-base to deploy to either GitHub pages or Netlify, like the eleventy-base-blog
project does.
npx @11ty/eleventy --pathprefix=eleventy-base-blog
Change exception case suffix for HTML files Jump to heading
If an HTML template has matching input and output directories, index.html files will have this suffix added to their output filename to prevent overwriting the template. Read more at the HTML template docs.
Exception Suffix | |
---|---|
Object Key | htmlOutputSuffix |
Default | -o |
Valid Options | Any valid string |
Command Line Override | None |
Example Jump to heading
module.exports = function(eleventyConfig) {
return {
htmlOutputSuffix: "-o"
}
};
Change Base File Name for Data Files Jump to heading
Added in v2.0.0 When using Directory Specific Data Files, looks for data files that match the current folder name. You can override this behavior to a static string with the setDataFileBaseName
method.
File Suffix | |
---|---|
Configuration API | setDataFileBaseName |
Default | Current folder name |
Valid Options | String |
Command Line Override | None |
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 Jump to heading
Added in v2.0.0 When using Template and Directory Specific Data Files, to prevent file name conflicts with non-Eleventy files in the project directory, we scope these files with a unique-to-Eleventy suffix. This suffix is customizable using the setDataFileSuffixes
configuration API method.
File Suffix | |
---|---|
Configuration API | setDataFileSuffixes |
Default | [".11tydata", ""] |
Valid Options | Array |
Command Line Override | None |
For example, using ".11tydata"
will search for *.11tydata.js
and *.11tydata.json
data files. The empty string (""
) here represents a file without a suffix—and this entry only applies to *.json
data files.
This feature can also be used to disable Template and Directory Data Files altogether with an empty array ([]
).
Read more about Template and Directory Specific Data Files.
module.exports = function(eleventyConfig) {
eleventyConfig.setDataFileSuffixes([".11tydata", ""]); // e.g. file.json and file.11tydata.json
eleventyConfig.setDataFileSuffixes([".11tydata"]); // e.g. file.11tydata.json
eleventyConfig.setDataFileSuffixes([]); // No data files are used.
};
Backwards Compatibility Note (v2.0.0
)
Prior to v2.0.0 this feature was exposed using a jsDataFileSuffix
property in the configuration return object. When the setDataFileSuffixes
method has not been used, Eleventy maintains backwards compatibility for old projects by using this property as a fallback.
module.exports = function(eleventyConfig) {
return {
jsDataFileSuffix: ".11tydata"
}
};
Transforms Jump to heading
Transforms can modify a template’s output. For example, use a transform to format/prettify an HTML file with proper whitespace.
The provided transform function must return the original or transformed content.
Transforms | |
---|---|
Configuration API | addTransform |
Default | {} |
Valid Options | Object literal |
Command Line Override | None |
module.exports = function(eleventyConfig) {
// Can be sync or async
eleventyConfig.addTransform("transform-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 );
return content; // no change done.
});
};
Transforms Example: Minify HTML Output
const htmlmin = require("html-minifier");
module.exports = function(eleventyConfig) {
eleventyConfig.addTransform("htmlmin", function(content) {
// Prior to Eleventy 2.0: use this.outputPath instead
if( this.page.outputPath && this.page.outputPath.endsWith(".html") ) {
let minified = htmlmin.minify(content, {
useShortDoctype: true,
removeComments: true,
collapseWhitespace: true
});
return minified;
}
return content;
});
};
Linters Jump to heading
Similar to Transforms, Linters are provided to analyze a template’s output without modifying it.
Linters | |
---|---|
Configuration API | addLinter |
Object Key | N/A |
Valid Options | Callback function |
Command Line Override | None |
module.exports = function(eleventyConfig) {
// Can be 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
.
module.exports = 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 Jump to heading
Added in v1.0.0
A Set
of lodash
selectors that allow you to include data from the data cascade in the output from --to=json
, --to=ndjson
, or the EleventyServerless.prototype.getOutput
method.
module.exports = function(eleventyConfig) {
eleventyConfig.dataFilterSelectors.add("page");
eleventyConfig.dataFilterSelectors.delete("page");
};
This will now include a data
property in your JSON output that includes the page
variable for each matching template.
Type Definitions Jump to heading
This may enable some extra autocomplete features in your IDE (where supported).
/** @param {import("@11ty/eleventy").UserConfig} eleventyConfig */
module.exports = function (eleventyConfig) {
// …
};
- More background information at Issue 2091.
Documentation Moved to Dedicated Pages Jump to heading
Copy Files to Output using Passthrough File Copy Jump to heading
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.
Data Deep Merge Jump to heading
- Documentation for Data Deep Merging has been moved to its own page under the Data Cascade.
Customize Front Matter Parsing Options Jump to heading
- Documented at Customize Front Matter Parsing.
Watch JavaScript Dependencies Jump to heading
- Documented at Watch and Serve Configuration.
Add Your Own Watch Targets Jump to heading
- Documented at Watch and Serve Configuration.
Override Browsersync Server Options Jump to heading
- Documented at Watch and Serve Configuration.