Project configuration

Enable or disable backlinks for the entire project. Default is true.

backlinks:
enabled: true

When set to false, backlinks will not be displayed on any page unless explicitly enabled at the page level.

Customize the heading text displayed above the backlinks section. Default is "See also".

backlinks:
title: "Referenced by"

The title appears as a heading above the list of pages that link to the current page.

Set the maximum number of backlinks to display on each page. Default is 12.

backlinks:
maxResults: 10

If a page has more inbound links than the maxResults value, only the first results will be shown. This helps keep the backlinks section manageable on highly referenced pages.

Set the base brand color for your project.

This is a convenient way to set the main theme color without using the full theme configuration. The default baseColor is #5495f1. To change the baseColor, use the following setting:

branding:
baseColor: "#8839ef"

The baseColor setting is equivalent to setting base-color in the theme configuration. For more advanced color customization, use the full theme system.

Optional logo label text. Default is Docs.

branding:
label: Docs

The label is rendered as the following label in the upper-left corner of the generated website, to the right of the title or logo.

One of the following:

1. The path to a logo file relative to the input, or
2. An inline <svg> logo

Default is null.

branding:
logo: static/logo.png

One of the following:

1. The path to a logo file (dark mode) relative to the input, or
2. An inline <svg> logo

Default is null.

branding:
logo: static/logo.png
logoDark: static/logo-dark.png

Set a logo image alignment relative to the title. Supported values include left and right.

Default is left.

branding:
logo: static/logo.png
logoAlign: right

The main text title added to the upper-left corner of the generated website.

The title can be used in conjunction with logo and logoDark. If a title and logo are configured, both will be added to the website. If only a title is configured, only the text title is used. If only a logo and/or logoDark are configured, only the logos are used.

branding:
title: Example.com

The above title would create the following branding title in the upper-left corner of the generated website.

To enable or disable the breadcrumb navigation within Neko projects. Default is true.

For Neko projects, breadcrumb navigation will be enabled by default.

To disable the breadcrumb navigation across an entire project, set the enabled parameter to false as shown in the following sample:

breadcrumb:
enabled: false # Disabled project wide

The home config allows customization of the initial node in the breadcrumb navigation. The parameter can accept either a string or a boolean value.

By default, the label used for the first item of the breadcrumb navigation will be the label of the project home page. This label can be customized or even removed.

Set with a custom label:

breadcrumb:
home: Home # custom label

Use a UIcon icon instead of text for the Home node:

breadcrumb:
home: ":icon-home:" # icon

Use an emoji:

breadcrumb:
home: ":rocket:" # emoji

The entire first item of the breadcrumb navigation, the "Home" node, can be removed by setting home: false:

breadcrumb:
home: false # Do not include the Home node

The separator config allows for the customization of the node separator used between each page label in the breadcrumb navigation.

Using a pipe | character as the separator:

breadcrumb:
separator: "|"

Using an icon as the separator:

breadcrumb:
separator: ":icon-circle-small:"

Cache busting configuration for the website resources, such as the JavaScript (.js) and CSS (.css) files.

Helps to ensure a loaded page refers to the most recent JavaScript and CSS resources.

Specifies the approach Neko will use for cache invalidation.

Default is query.

cache:
strategy: query

Below are demo URLs generated for corresponding cache.busting.strategy options:

<script type="text/javascript" src="/resources/js/neko.js" />

<script type="text/javascript" src="/resources/js/neko.v1.10.js" />

<script type="text/javascript" src="/resources/js/neko.js?v=1.10" />

An optional unique token used for website resource cache invalidation.

If specified, the provided value is used for all invalidatable resources as is.

If not specified, the default token having the following structure is used: {Neko version}.{total milliseconds elapsed since 2000-01-01}

cache:
token: v5

By default, if the url is set, Neko will automatically generate a CNAME file. This can be disabled by setting cname: false.

cname: false

If you do manually create a CNAME file, please ensure the value in the CNAME file matches the value set in the url.

The repository URL where the source files for this project are located.

Setting a repo value will enable the Edit this page links on all content pages.

edit:
repo: "https://github.com/<your-organization>/<your-repo>/"

It is also possible to configure the links to point directly to the /edit/ view of the page:

edit:
repo: "https://github.com/<your-organization>/<your-repo>/edit/"

An optional base path to a directory within the repository.

The base can be configured with an optional path to a directory within the repo.

The following sample demonstrates how edit.base would be configured if the .md source files for this project are stored within the /src/docs sub-directory within the repo.

edit:
repo: "https://github.com/your-organization/your-repo"
base: /src/docs

The final Edit this page URL constructed by Neko for the sample above would be https://github.com/your-organization/your-repo/blob/main/src/docs/your-page.md.

Point to a custom branch within the repo. Default is main.

edit:
repo: "https://github.com/your-organization/your-repo"
branch: master

A custom label for the link. Default is "Edit this page".

edit:
repo: "https://github.com/your-organization/your-repo"
label: Edit on GitHub

To enable or disable the live editor. Default is true.

Set to false to disable and hide the live editor.

editor:
enabled: false # Default is true

Neko can exclude files or folders from being built or copied to the output by configuring an exclude list within your projects neko.yml file.

Exclude patterns are similar to allowable patterns within a .gitignore file. The wildcards ?, *, **, and ! are supported.

The following sample demonstrates how to exclude an entire draft/ folder, any folder that ends with *_temp/, and one specific /src/temp.md file.

exclude:
- "draft/"
- "*_temp/"
- "/src/temp.md"

You could exclude everything in your project with by adding exclude: [ * ].

To explicitly include any files or folders that might have been excluded, please see the include config.

A custom path to a .ico or .png file to be used as the favicon. Default is null.

The path is relative to the input.

favicon: static/favicon.png

By default, Neko will look for a favicon.ico or favicon.png within the root of the input. The favicon config would typically only be used if you want to store the favicon file in a subfolder of the output root.

Site-wide copyright statement that will be added to the footer of each page. Supports Markdown syntax and {%{{{ year }}}%} variable.

{%{

footer:
copyright: "© Copyright {{ year }}. [Example, Inc.](https://example.com/) All rights reserved."

}%}

The footer.links have the same configuration options as links.

footer:
links:
- text: License
link: license.md

A list of file names to treat as default HTML files.

By default, Neko will treat all of the following files as default pages if they are within a folder.

generator:
directoryIndex:
altNames:
- index.html
- index.htm
- default.html
- default.htm

If you have a default.htm file within a folder and do not want it to be treated as a default page, then set altNames to the following:

generator:
directoryIndex:
altNames:
- index.html

Specifies if the default document file name should be appended to resolved URLs. By default, Neko does not append the default file name.

If false, the generated link will be /guide/. If true, the generated link will be /guides/index.html.

generator:
directoryIndex:
append: true # default is false

Using append: true in combination with the search.preload config allows for offline file system browsing of your generated website without having to install Neko and start a web server using neko start. The following sample demonstrates how to configure:

search:
preload: true

generator:
directoryIndex:
append: true

The default HTML document file name generated by Neko.

generator:
directoryIndex:
name: default.htm # Default is index.html

Configures url kind preference for resolved urls. Supported values: source, relative, and root.

generator:
paths: relative

Instructs Neko on how to recase the project file and folder names created by the author. Default is all.

By default, Neko will recase all the generated file and folder names to all lowercase.

To have Neko NOT change the casing of any of your file or folder names, set recase to none.

generator:
recase: none

By setting trailingSlash: false in the project config, authors can instruct Neko to remove (or not add) the trailing / character when constructing links from paths to Markdown files.

For example, if you have a simple link in your project to [Example](/guide/example.md), Neko will create the link as /guide/example/. By setting trailingSlash: false in your project, Neko would then create the link as /guide/example.

It is best practice to include the trailing slash and by default, Neko will automatically add the trailing slash to links that are missing.

generator:
trailingSlash: false # default is true

Set to a local path or external URL. By setting the link value, the Hub will be enabled. To disable, remove the link config.

hub:
link: https://example.com/ # default is empty

Custom text value used to set the title attribute of the hub link.

hub:
link: https://example.com/
alt: Go to example.com

Sets the target attribute of the hub link and specifies which window or tab to open the link into.

hub:
link: https://example.com/
target: blank

If no target is configured, the link will open in the current tab.

The target can be set to any value, although blank is common and will open the link in a new tab. Neko will automatically transform the value blank into _blank which is the actual value required by the browser to indicate that a hyperlink should be opened in a new tab.

There are several other values that may be prefixed with an _ character, including self, parent, and top. The following table demonstrates some common scenarios and naming convention used by Neko to normalize the target values.

Neko can explicitly include files or folders that might have been excluded by default or excluded within the exclude config.

Include patterns are similar to allowable patterns within a .gitignore file. The wildcards ?, *, **, and ! are supported.

The following sample demonstrates how to include all .py files, all .js files that start with the name demo, and the entire contents of any www folder within the project.

include:
- "*.py"
- "demo*.js"
- "**/www/**"

You could explicitly include everything in your project with include: [ "*" ], but be careful as all files within your input will be publicly availble once your website is published. We would not recommend doing this, but it's your call.

Neko treats all .md and .yml files as parsable content files that will be converted into .html files and are not copied over to the output. All other included file types would be copied straight across to the output unchanged and become static files that can be linked to.

By default, if Neko discovers any of the following file types, they will be automatically included and copied over to the output unchanged. If you require any other file types, they would need to be explicitly added to the include config.

File types that are automatically included:

1. *.ai
2. *.bmp
3. *.eps
4. *.gif
5. *.heif
6. *.htm
7. *.html
8. *.jpeg
9. *.jpg
10. *.pdf
11. *.png
12. *.svg
13. *.tiff
14. *.txt
15. *.webp
16. *.zip

By default, if Neko discovers any of the following folders anywhere within the project, the folder and its entire contents will be copied over to the output unchanged. If you require any other folders, please add to the include config.

Included folders:

1. **/static/**
2. **/public/**
3. **/assets/**
4. **/resources/**

If you would rather not include certain folders, files, or file types, please add the pattern to the exclude config.

Custom path to the input directory. Default is ..

The path is relative to the neko.yml location.

input: ./src

Google Analytics ID value.

integrations:
googleAnalytics:
id: <id>

Replace the <id> with your Google Analytics measurement id. For example:

integrations:
googleAnalytics:
id: A-BCDEFGHIJ1

Google Tag manager ID value.

integrations:
googleTagManager:
id: <id>

Replace the <id> with your Google Tag Manager measurement id.

The default profile image to return from Gravatar queries whenever no image is assigned to the queried email address. Default value is mp.

Either a full URL to the image can be configured or one of the options listed below:

Value	Sample
404	Broken image
mp (default)
identicon
monsterid
wavatar
retro
robohash
blank	Blank image

Please see the Default Image documentation on the Gravatar website.

Whether Neko should use Gravatar to pull profile images. Default is true.

Setting to false will show the default image or specified resource.

When you setup your project within Plausible, you enter a Domain value which is then used to set the integrations.plausible.domain config within your neko.yml project configuration file.

integrations:
plausible:
domain: <string>

Plausible can also send statistics to multiple dashboards by configuring a comma-separated list of domains. For example:

integrations:
plausible:
domain: domain1.com,domain2.com,subdomain.yourdomain.com

Check out the Plausible documentation for more details.

The Plausible service can be self-hosted and your Neko project can be configured to use your custom host.

integrations:
plausible:
host: <string>

A typical host project configuration would look like the following sample:

integrations:
plausible:
host: plausible.example.com

If no transfer protocol is supplied, Neko will default the host value to use https.

All of the following sample host values are supported:

host: example.com
host: docs.example.com
host: https://example.com
host: http://example.com
host: example.com/js/plausible.js
host: docs.example.com/js/plausible.js

The link text label.

links:
- text: Demos
link: https://demo.example.com/

The URL to use for the link. The link can be a .md file name, or to any internal path, or to any external URL.

If a .md file set, such as sample.md, Neko will automatically resolve the path and in the generated website, the sample.md value will be replaced with the path to the actual generated HTML file.

links:
- text: About us
link: /about/

An icon to use with the link. Default is null.

links:
- text: Issues
link: https://github.com/neko/neko/issues/
icon: bug

Options include using a UIcon name, Emoji shortcode, <svg> element, or a path to an image file.

icon: rocket

icon: ":rocket:"

icon: <svg>...</svg>

icon: ../static/rocket.png

The position for the icon relative to the link text. Either left or right. Default is left.

links:
- text: Demos
link: https://demo.example.com/
icon: link-alt
iconAlign: right

Sets the target attribute of the hyperlink and specifies which window or tab to open the link into.

links:
- text: Demos
link: https://demo.example.com/
target: blank

If no target is configured, the link will open in the current tab.

The target can be set to any value, although blank is common and will open the link in a new tab. Neko will automatically transform the value blank into _blank which is the actual value required by the browser to indicate that a hyperlink should be opened in a new tab.

There are several other values that may be prefixed with an _ character, including self, parent, and top. The following table demonstrates some common scenarios and naming convention used by Neko to normalize the target values.

Allows defining a dropdown (flyout) menu of sub-links. If items are present, the top-level link becomes a trigger for the menu.

Each item in the list supports text, link, icon, target, and description.

links:
- text: Products
items:
- text: Analytics
link: /products/analytics
icon: chart-pie
description: Understand your traffic
- text: Security
link: /products/security
icon: lock
description: Protect your data

A short description for the link. This is primarily used within items to provide more context in flyout menus.

links:
- text: Features
items:
- text: Components
link: /components
description: Explore built-in components

Allows defining a footer section within a flyout menu. These items are displayed at the bottom of the dropdown in a distinct style.

This property is only used when items are also defined.

links:
- text: Resources
items:
- text: Blog
link: /blog
footerItems:
- text: Contact Sales
link: /contact
icon: phone-call

You can switch the locale to any other supported language by providing the corresponding ISO language code as listed below.

Default is en.

The following sample demonstrates switching the project to use French.

locale: fr

Switches between soft and hard line break modes. The option instructs Neko in what way a regular line ending should be handled.

• in soft mode, regular line breaks are processed as soft breaks (no <br /> is emitted to HTML markup), unless a line contains 2+ spaces before a line break.
• in hard mode, regular line breaks are always emitted as <br /> HTML elements.

Default is soft.

markdown:
lineBreaks: soft # or, hard

Common site-wide suffix appended to the html <title> element of all pages. Default is null.

meta:
title: " | Example.com - Widgets for the internet"

Using the sample above, if we had an About us page, the final <title> would be:

<title>About us | Example.com - Widgets for the internet</title>

Controls how the sidebar navigation is created and functions. The default functionality is to create the navigation as an expandable Tree structure. The default value for mode is default.

The following sample demonstrates how to configure the "stacked" navigation structure:

nav:
mode: stack

To convert only one top-level directory to a stack type layout, please see the Page nav setting.

Controls how icons are displayed in the left sidebar navigation. The default value is all, which shows all icons or reserves space for all icons within the navigation.

The following sample demonstrates how the icon mode can be configured in your neko.yml file:

nav:
icons:
mode: all|none|folders|pages|top # Default is all

To hide icons for all pages and folders, add the following setting to your project neko.yml configuration file:

nav:
icons:
mode: none

The nav.icons.mode setting can be used in conjunction with nav.mode: stack to handle many different icon and navigation rendering combinations.

Controls how the Next/Previous navigation buttons are displayed and whether the page is included in the navigation sequence.

The default value is show.

nextprev:
mode: hide

The nextprev.mode setting can be configured at three levels with the following precedence:

1. Page level in individual .md files
2. Folder level in the folder readme.md or index.yml files
3. Project level in your Project neko.yml file

===

outbound

The outbound configuration gives you the flexibility to customize the behavior of outbound links in your Neko project. It allows you to control which links are treated as outbound, where they open, what icon is used, and even exclude or include specific domains. For instance, example.com.

If outbound is enabled, Neko will find all external (outbound) links within the project, add a trailing icon, and set the link to open in a new tab when clicked.

enabled

Controls whether the outbound links feature is enabled.

The default is true.

The following sample demonstrates disabling the outbound functionality:

outbound:
enabled: false

Provides a way to specify custom attributes to be added to the outbound links. The default value is empty/null.

The following sample demonstrates how to add the attribute rel="noopener noreferrer" to all outbound links:

outbound:
custom: 'rel="noopener noreferrer"'

Defines the icon to be used for outbound links and accepts all the same options as the links.icon config. The default value is link-external .

outbound:
icon: link-alt

If you would prefer to keep the outbound functionality enabled, but not include the icon, please set icon: "". The following sample demonstrates:

outbound:
icon: ""

Determines the alignment of the icon for outbound links and accepts the same options as the links.iconAlign config. Acceptable values are right or left. The default value is right.

outbound:
iconAlign: right

Specifies the target attribute for the outbound links. The default value of "blank" opens the link in a new window or tab.

outbound:
target: blank

A list of outbound link patterns to be excluded from being captured by the Neko outbound functionality. This is useful if you do not want certain links to open in new tabs.

This configuration accepts similar path patterns as the exclude config.

The following sample demonstrates excluding all links pointing to example.com.

outbound:
exclude:
- example.com

Please also see outbound.include.

A list of outbound link patterns to be included for the Neko outbound functionality. This is useful if you only want certain links to open in new tabs. The default value of * includes all links.

This configuration accepts similar path patterns as the include config.

The following sample demonstrates including only links that point to example.com.

outbound:
include:
- example.com

If any item is added to the include list, by default, all other paths will be excluded. Please also see outbound.exclude.

Custom path to the output directory. Default is .neko.

The path is relative to the neko.yml location.

output: ./docs

The Powered by Neko branding can be removed by setting to false.

poweredByNeko: true # Set to `false` to remove.

Controls the default color scheme for the website. The default value is system, which will automatically switch between dark and light modes based on the visitor's system preference.

To configure Neko to always render in dark mode, add the following to your neko.yml:

scheme:
mode: dark

To always render in light mode:

scheme:
mode: light

To use the system preference (default):

scheme:
mode: system

Keyboard key to set the cursor focus into the search field. Default is k.

The following sample demonstrates how to change the search hotkey to use / instead of the default k:

search:
hotkeys:
- "/"

Max number of search results to render. Default is 20.

search:
maxResults: 20

Min number of characters required in a search query. Default is 2.

The following sample demonstrates how to configure search.minChars with a new value:

search:
minChars: 3

The search index creation mode. Default is full.

The following sample demonstrates how to configure search.mode with a new value:

search:
mode: partial

Message rendered when no results were found. Default is "Sorry, no results found.".

search:
noResultsFoundMsg: Sorry, no results found.

Placeholder text rendered on the search component. Default is "Search".

search:
placeholder: Search

Specifies if the search index should be preloaded. Default is false.

search:
preload: true # Default is false

Using preload: true in combination with the generator.directoryIndex.append config allows for offline file system browsing of your generated website without having to install Neko and start a web server using neko start. The following sample demonstrates how to configure:

search:
preload: true

generator:
directoryIndex:
append: true

Serve the website from this host location. Default is localhost.

serve:
host: 127.0.0.1

By default, the Neko development web server will serve from http://localhost:5001, although the port could be dynamically assigned if port 5001 is already in use.

A custom port value can also be assigned.

serve:
host: 127.0.0.1:5005

A custom --host value can also be passed as an argument to the neko start and neko serve commands. If included, the --host value will override the host set within your neko.yml project configuration file.

neko start --host 127.0.0.1              # serve from a custom host
neko start --host 127.0.0.1 --port 5005  # serve from a custom host and port

A custom port for the internal Neko development web server to use when hosting locally. Default is 5001.

serve:
port: 5005

If the default port is already being used by another service, Neko will auto-increment the port number until it finds an open port to host from.

If a custom port is explicitly configured in the neko.yml and if that port is already being used by another service, Neko will write a message to the console and exit. In that scenario, because the port was explicitly configured, Neko will not attempt to auto-increment.

A custom --port value can also be passed as an argument to the neko start and neko serve commands. If included, the --port value will override the port set within your neko.yml project configuration file.

neko start --port 5005  # serve from a custom port

During neko start and neko serve, the mode configuration instructs the web server on where to host files from.

If memory, the entire website is built and then stored in memory during development with no files being written to disk.

If disk, the entire website is built and written to disk, then the web server will host those files from their disk location.

Default is memory.

serve:
watch:
mode: disk

The command neko build will always build and write all files to disk. The memory configuration is not an option with neko build. The Neko GitHub Action uses neko build. The command neko start is only to be used during local development and not on a live production web server.

Instructs the local web server on how it should listen for file changes.

If false, the native filesystem event listeners are used to monitor for file changes.

If true, Neko will poll for file changes within your projects input directory. By default, the polling interval is 1000 milliseconds (1 second).

The poll interval is configurable by setting a number value. For instance, setting polling: 500 would configure a 500ms interval.

Default is false.

serve:
watch:
polling: true

Configure how thorough Neko is while looking for changed files.

Default value is optimal.

The showSidebarFilter project setting controls the visibility of the filter component in the left sidebar above the navigation tree. Default is true.

By default, this setting is true, meaning the filter component is displayed. If set to false, the filter component will be hidden, allowing for a more streamlined sidebar layout. This option can be useful for simplifying the user interface in projects where filtering topics is not necessary.

showSidebarFilter: false

A list of glob patterns specifying files and directories that Neko should skip during the build process. Default is an empty list [].

By default, Neko scans and parses all Markdown files in your project directory (except for some system or hidden directories). The ignore property allows you to explicitly exclude files or entire directories from being processed into HTML or included in your navigation.

ignore:
- "drafts/**"              # Ignore everything in the drafts folder
- "private-docs/*.md"      # Ignore markdown files in private-docs
- "**/archived-*"          # Ignore files prefixed with archived- anywhere

These patterns use standard Microsoft.Extensions.FileSystemGlobbing syntax evaluated relative to your project's input directory.

A list of code block reference language strings to enable line numbering on. Default is null.

snippets:
lineNumbers:
- js
- json

Configuring the "*" wildcard will enable line numbering for all code block types, including code blocks with no explicit reference language.

snippets:
lineNumbers:
- *

Enabling line numbering site wide on code blocks with no explicit reference language is configured with the none "none" specifier.

snippets:
lineNumbers:
- none

Set to false to instruct Neko to not open the default web browser when the command neko start is run. By default, Neko will open a web browser when neko start is run.

The default is true.

The following sample demonstrates how to prevent the default web browser from opening during neko start:

start:
open: false

Using the CLI command neko start -n or neko start --no-open will also prevent the default web browser from being opened.

A project-wide option to enable or disable the Neko content templating engine. Default is true.

templating:
enabled: true # Set to false to disable

The templating engine can also be disabled on a per-page basis by setting templating: false in the page metadata.

Specifies if Liquid syntax {% ... %} is enabled. If liquid: true is set, Neko is incompatible with GitBook style of component configuration.

Default is false.

templating:
liquid: false # Set to true to enable

Sets the maximum number of iterations allowed for loop statements in templates. This is a safety mechanism to prevent infinite loops and excessive resource consumption during template rendering.

Default is 1000.

templating:
loopLimit: 1000 # Maximum loop iterations allowed

When a template contains loops that exceed the configured loopLimit, Neko will throw a build error and halt the build process.

templating:
loopLimit: 500 # Reduce limit for stricter control

Setting loopLimit: 0 disables loop limit enforcement entirely, allowing unlimited loop iterations. Use with caution as this can lead to performance issues or build timeouts with poorly designed templates.

templating:
loopLimit: 0 # Disable loop limit (not recommended)

Common use cases

Large datasets: If your templates process large collections of data (such as comprehensive lists, extensive navigation menus, or bulk content generation), you may need to increase the loop limit:

templating:
loopLimit: 5000 # For processing large datasets

Strict resource control: For projects where template performance is critical, you can reduce the limit to catch potentially problematic templates early:

templating:
loopLimit: 100 # Strict limit for performance-critical projects

Error handling

When the loop limit is exceeded, Neko will display an error message similar to:

ERROR: [template.md:1] Evaluation error. Exceeding number of iteration limit `1000` for loop statement.

This error indicates that a template contains loops that process more items than the configured limit allows. To resolve this, either:

1. Increase the loopLimit value if the large loop is intentional
2. Optimise the template to reduce the number of loop iterations
3. Split large datasets into smaller, more manageable chunks

Performance

Loop limits help maintain build performance by preventing runaway templates. Consider the following when setting loop limits:

• Build time: Higher limits allow more complex templates but may increase build times
• Memory usage: Large loops can consume significant memory during template processing
• Template complexity: Nested loops count towards the total iteration limit

For most projects, the default limit of 1000 iterations provides a good balance between flexibility and performance protection.

The base theme configures the light mode appearance and serves as the foundation for your site's design. All theme variables can be customized within this section.

theme:
base:
base-color: "#8839ef"
base-link-weight: 500
nav-item-text-active-weight: 700

theme:
base:
# Primary brand color
base-color: "#8839ef"
base-bg: "#eff1f5" # Base background color

# Variants
primary: "#1e66f5" # Blue
success: "#40a02b" # Green
danger: "#d20f39"  # Red
warning: "#df8e1d" # Yellow

# Typography
base-link-weight: 500

# Navigation
nav-item-text-active-weight: 700

The dark theme specifically targets dark mode appearance. When the website is switched to dark mode, the dark theme variables override the [[#theme-base]] variables. The following demonstrates how to configure the dark theme variables:

theme:
dark:
base-color: "#ca9ee6"
base-bg: "#303446"

The heading depth to include in the right Table of Contents.

The default is 2-3.

toc:
depth: 2-3

The toc can be configured at the Project or Page levels.

Configuring the toc at the Page level overrides the Project level settings.

Acceptable values for depth include:

A custom label for the top of the Table of Contents column.

toc:
label: On this page

The base URL of your website.

url: example.com

The url can also be a subdomain.

url: docs.example.com

If you deploy your Neko generated website into the subfolder of another website, add the subfolder in the url. For example, if the website will be available at https://example.com/docs, add that docs folder name to the url.

url: example.com/docs

If no protocol is supplied, such as https or http, Neko will assume https. A protocol can be explicitly defined by passing in the url.

url: http://example.com/docs/

Another common scenario for setting a url is when using GitHub Pages without a custom CNAME.

For instance, if your GitHub organization was CompanyX and your repo was named docs, the URL to your GitHub Pages hosted website would be https://companyx.github.io/docs/.

Neko needs to know where your website will be hosted, so the url configuration for the above scenario would be:

url: companyx.github.io/docs

Set to true to enable the generation of a sitemap.xml file in the output directory. The sitemap will include all generated pages using the url property as the base URL. If no url is provided, it defaults to localhost.

The default is false.

sitemap: true
url: https://example.com/docs