Configuration

This is an extensive overview of all configuration options for LFPDocs. For information on how to apply these configurations, refer to the configuration guide.

Type Support

Types for the configuration are exported from the package:

// TypeScript ESM:
import type { LFPDocsConfig } from '@lowfat/eleventy-plugin-lfp-docs';
// JSDOC:
/** @type {import("@lowfat/eleventy-plugin-lfp-docs").LFPDocsConfig} */

The given type definitions in this reference are noted in TypeScript, refer to its documentation if anything is unclear.

LFPDocsConfig

additionalPages

• Type: LFPDocsPage[]

Link information for pages that do not belong to a topic; entries get added to the site's header menu.

allowEdit

• Type: string

Whether to show a link to the documentation page's source; works for GitHub and Codeberg.

banner

Banners let you include arbitrary code right at the beginning of the page's main content or near the end, before metadata, edit links, and pagination. This setting only applies to the lfp-base-documentation layout used by LFP Docs for documentation pages; other layouts are unaffected.

Use it to let visitors know of new versions, features, or changes. Or some friendly kind of advertisement, if your project or organization depends on it.

bottom (unsafe HTML)

Lets you insert an arbitrary string that gets interpreted as HTML before a page's metadata and pagination.

top (unsafe HTML)

Lets you insert an arbitrary string that gets interpreted as HTML as the first child of the page's main content container, above the page title.

baseUrl

• Type: string
• Default: ""

The base URL that gets prepended to all relative links (when using the default layout); useful when deploying from a subdirectory.

description

• Type: string

A concise description of your project or documentation.

dir

• Type: LFPDocsDirConfig

A collection of relevant directories; see individua entries for detailed information.

favicon

• Type: string

Path to favicon, relative to output directory (defined in Eleventy configuration).

footer

• Type: boolean

Whether to show the site's footer; empty by default, populate with footerCopyright and footerMenu.

footerCopyright (unsafe HTML)

• Type: string

Free-form HTML for copyright information in the page footer; only applies if footer is true.

footerMenu (unsafe HTML)

• Type: LFPDocsPage[]

List of pages to be added to the footer menu; only applies if footer is true.

i18n

• Type: { dict: Record<string, Record<string, string>>}

This object collects all settings related to internationalization. Refer to the guide to learn more about setting up this feature.

dict

To edit LFP Docs's internationalization of common text, pass in a dictionary with the following signature:

{
    "skip to main content": {
        // use a two-character language code as key, with the approbriate translation for the above key as value
        "de": "Zum Hauptinhalt springen"
    }
}

Refer to this list of terms for a complete list of translateable text:

List of terms

• change language
• close top menu
• edit this page
• last updated
• menu
• next page
• on
• on this page
• open top menu
• previous page
• return to top
• skip to main content

ìgnore

• Type: string[]

Add a list of project relative paths that are ignored when building the documentation.

markExternalLinks

• Type: boolean

Whether to mark external links with an icon (applies only to Markdown content).

lang (unsafe HTML)

• Type: string
• Default: "en"

Set global language attribute (does not change interface language). Accepts a language string compatible to BCP 47. When setting a right-to-left language, make sure to either set langDir globally in the configuration or, alternatively, in the page's or directory's frontmatter setting for proper display.

langDir

• Type: "ltr" | "rtl"

Specifies preferred flow direction of text, ltr (left to right) or rtl (right to left).

layout

• Type: string
• Default: "lfp-base-layout"

Use a custom layout instead of the default one; specify path relative to _includes (defined in Eleventy configuration). The default value references LFPDocs's standard theme.

locales (unsafe HTML)

• Type: Record<string, string>

A list of locale options for the site, with keys as BCP-compatible language tags, and values as printable names. Values get applied to HTML, beware of injection attacks.

locales: {
  de: 'Deutsch',
  es: 'Español',
  fr: 'Français',
  pt: 'Português',
},

logo

• Type: string

Path to logo, relative to output directory (defined in Eleventy configuration). Appears in the header section of each page.

linkAttrs

• Type: [string, string][]

Add optional <link> elements to be added to the <head> of each page, with the first index being rel, and second being href.

metaAttrs

• Type: [string, string][]

First index as name, second as content. Add arbitrary meta information to the head of each page.

package

• Type: LFPDocsExternalService

Add information about the package documented by this website. If it is a known package provider, a clickable icon will be added to the site's main navigation menu.

passthroughCopies

• Type: Record<string, string>

Keys as source file/directory (relative to project root, /docs by default), values as target file/directory.

repository

• Type: LFPDocsRepositoryConfig

Add information about the repository documented by this website. If it is a known source control provider, a clickable icon will be added to the site's main navigation menu.

returnToTop

• Type: boolean

Whether to show a return to top link in the page's table of contents on smaller screens.

scripts

• Type: string[]

Pass a list of script file names (including file extensions) to include them in each page's <head>. Paths must be relative to the script source directory specified in dir.scripts. Refer to the asset handling guide for more information on including custom content.

search

• Type: boolean
• Default: true

Whether to include search component and index the site. Hides the search component on each page and disables indexing by Pagefind.

showGenerator

• Type: boolean
• Default: true

Whether to include the site generator in a meta tag; provides visibility for Eleventy.

styles

• Type: string[]

Pass a list of style file names (including file extensions) to include them in each page's <head>. Paths must be relative to the style source directory specified in dir.styles. Refer to the asset handling guide for more information on including custom content.

title (unsafe HTML)

• Type: string

Title for project or documentation. Appears in the header section of each page.

titlePrefix (unsafe HTML)

• Type: string

An optional subtitle with which the text content of <title> gets prefixed.

toc

• Type: boolean
• Default: true

Whether to show a table of contents on the documentation pages. Can be overwritten on an individual level for each page in the frontmatter.

topics (unsafe HTML)

• Type: string[]

Set a list of topics, function as "super-categories", placed in the site header menu.

Use this if…

• …you want to reorder how topics are added to the header menu
• …you want to exclude certain topics from being placed in the header menu.

version (unsafe HTML)

• Type: string
• Default: package.json -> version

Add an optional version tag of the project or documentation to the site's top header menu. By default, LFPDocs tries to fetch your project's current version from its package.json, or shows nothing at all in case it doesn't find anything.

LFPDocsDirConfig

data

• Type: string
• Default: "_data"

The Eleventy data directory; pass if you want the plugin to know that location before or during plugin execution (currently unused).

includes

• Type: string
• Default: "_includes"

The Eleventy includes directory; pass if you want the plugin to know that location before or during plugin execution (currently unused).

input

• Type: string
• Default: "docs"

The Eleventy input directory; pass if you want the plugin to know that location before or during plugin execution (currently unused).

layouts

• Type: string
• Default: "_layouts"

The Eleventy input directory; pass if you want the plugin to know that location before or during plugin execution (currently unused).

output

• Type: string
• Default: "_site"

The Eleventy output directory; pass if you want the plugin to know that location before or during plugin execution (currently unused).

scripts

• Type: string
• Default: "assets/scripts"

Output directory for styles.

styles

• Type: string
• Default: "assets/styles"

Output directory for scripts.

LFPDocsExternalSource

Information about external services, such as repository providers or package managars (e.g., GitHub or npm).

host (unsafe HTML)

• Type: string

The external service's human-readable hostname, gets published on the layout.

url

• Type: string

The URL to the external service.

LFPDocsPage

Used by additionalPages and footerMenu to build concise menu defintions.

title (unsafe HTML)

• Type: string | Record<keyof LFPDocsConfig["locales"], string>

The human-readable and printable title of the page, Markdown allowed. Alternatively, pass in an object with your site's locales as keys and their respective translations as values. LFP Docs then picks the right translation for each page.

url

• Type: string

The relative or absolute path to the page.

LFPDocsRepositoryConfig

Extends LFPDocsExternalService.

branch

• Type: string

The branch on which the documentation lives inside the repository. Used for directy linking to documentation source.