Page configuration
Individual .md pages can be configured using the Frontmatter metadata section added to the top of the page.
---
label: Sample
layout: page
order: 100
---
# Sample
This is a sample page demonstrating page metadata.
Default pages
Separate .yml file
If you would prefer to keep the page metadata separated and placed outside of the .md content page, the config can be moved into a paired .yml file.
For instance, sample.md would need a matching sample.yml file. The separate .yml file must have the exact same filename as its paired .md page.
Both .yml and .yaml extensions are supported.
Adding your configs into the top metadata section of a .md page, or into a separate .yml file is just a matter of preference. Both techniques produce the same result.
# Sample
This is a sample page demonstrating page metadata.
label: Sample
layout: page
order: 100
If you add configs to both locations, the page metadata takes precedence, even if they are different configs.
If you add one or more configs to a .md page, Neko will not look for nor read the separate .yml file. Just use one or the other, but not both.
See folder configuration for details on how to configure a folder.
author
The configuration name authors is also supported. The name authors is an alias of author and both can be used interchangeably.
author : string, list, or object
The author or multiple authors of this page.
---
author: Frank
---
---
author: frank@example.com
---
An author object can also be configured with specific values for the name, email, link, and avatar.
The author config is very flexible and can accept one or more author configurations and even a list of mixed types. The following sample demonstrates adding a list of authors. Two authors are added by name and a third is added only by their email address.
---
authors: [Frank, Annette Jones, steffen@example.com]
---
Mixed author types are also permitted, including adding a list of authors by name, email, or author configuration objects.
---
# Mix of author types
authors:
- name: Frank Esposito
email: frank@example.com
link: https://twitter.com/frank
avatar: https://example.com/frank.jpg
- Annette Jones
- steffen@example.com
---
avatar
email : string
---
author:
email: frank@example.com
---
link
link : string
---
author:
link: https://twitter.com/frank # custom link take precedence
---
name
name : string
---
author:
name: Frank Esposito
---
backlinks
The backlinks configuration controls the display of inbound links from other pages in your project on this specific page. Backlinks help users discover related content by showing which pages reference the current page.
enabled
enabled : boolean
Enable or disable backlinks for this page. Default is true.
---
backlinks:
enabled: false
---
Set to false to disable backlinks on this page, even if enabled at the project level.
title
title : string
Customize the heading text displayed above the backlinks section on this page. Default is "See also".
---
backlinks:
title: "Related pages"
---
This overrides the project-level title setting for this specific page.
maxResults
maxResults : number
Set the maximum number of backlinks to display on this page. Default is 12.
---
backlinks:
maxResults: 3
---
This overrides the project-level maxResults setting for this specific page.
See also Project configuration of backlinks.
breadcrumb
breadcrumb : boolean
The breadcrumb config controls whether to include the breadcrumb navigation on this page. Default is true.
Set to false to disable the breadcrumb navigation on this page.
breadcrumb: false
It is also possible to disable the breadcrumb navigation on all pages within a folder by setting breadcrumb: false in the folderhindex.yml configuration file or the folder default page, such as default.md, readme.md, or index.md.
category
The configuration name categories is also supported. The name categories is an alias of category and both can be used interchangeably.
category : string or list
A category for this page.
A single category or a list of categories can be configured in each .md page you would like to categorize.
The category is meant to be a broad grouping of content, where tags are meant to describe specific details of the content in that particular page. A page can belong to multiple (zero to many) categories and have multiple (zero to many) tags.
All of the following are acceptable techniques for configuring a single category or multiple categories.
---
category: news
categories: news
category: [news, general]
categories: [news, general]
category:
- news
- general
categories:
- news
- general
---
If a category is configured in the page metadata, the category is added to the top of the page under the main title.
Individual category summary pages will be automatically generated by Neko at <url>/categories/<category>, plus an additional <url>/categories index page which lists all categories in the project.
date
date : string
A custom publish date for this page.
If a date is configured, Neko will add the Published date to the top of the page, just under the main title.
The date must be provided in the yyyy-mm-dd ISO format or yyyy-mm-ddThh:mm if you want to include a date and a time.
date: 2020-11-25 # November 25, 2020
date: 2020-11-25T15:30 # November 25, 2020 at 15:30 (3:30 PM)
The date is used by Neko to order blog pages. Newer blog pages are ordered first.
expanded
expanded : boolean
Determines whether this folder should be expanded in the tree navigation on initial page load. Default is false.
Set to true to expand the folder node in the navigation.
expanded: true
The expanded option only applies to folders when configured within an index.yml folder configuration file.
Setting expanded: true within the metadata of an .md page or the paired .yml file will be ignored.
icon
icon : string
image
image : string
By default, Neko will try to find the first image on the page and use that image as the feature image to highlight when creating a summary of the page.
You can customize the feature image by setting the image config to any local path or external image hosted elsewhere.
Local path
Configure a path to a local file stored within the project.
image: ../static/feature-image1.jpg
External image
Configure a URL to any image hosted elsewhere.
image: https://example.com/static/feature-image1.jpg
label
label : string
Custom label for the navigation node for the current page. Default is null.
label: Custom label
layout
layout : string
The layout for the page. Default is default.
Supported values: default, central, page, and blog.
| Layout | Description |
|---|---|
default |
The default layout for all .md pages. The page is added to the main navigation. |
page |
Similar to default layout, but is not added to the main navigation. |
central |
A page with no left or right sidebar columns. |
blog |
A blog page layout. Blog pages are not added to the main navigation and include blog specific < Newer and Older > navigation buttons at the bottom of each blog page. |
layout: page
meta
title
title : string
A custom value for the <title> meta tag.
If set, the value will completely override any <title> meta tag value generated by Neko.
Default is null.
---
meta:
title: "A 100% custom title meta tag value"
---
# Sample
With the above sample, the <title> will be:
<title>A 100% custom title meta tag value</title>
Without the meta.title set, by default, the <title> would be:
<title>Sample</title>
This meta.title config is not to be confused with the Page title config, which we recommend not using.
This meta.title config is also not to be confused with the Project level meta.title config.
description
description : string
A custom value for the <meta name="description"> meta tag.
If set, the value will be used as the content attribute of the <meta name="description"> tag in the <head> of the page. This value will also be used for the og:description and twitter:description meta tags.
---
meta:
title: "Profile Page"
description: "This is a custom description"
---
# Profile
With the above sample, the following meta tags will be generated:
<meta name="description" content="This is a custom description">
<meta property="og:description" content="This is a custom description">
<meta name="twitter:description" content="This is a custom description">
nav
Navigation configuration options to control the behavior of the left sidebar navigation.
badge
badge : string or object
Add a [badge] to the navigation item for this page in the left sidebar. The badge can be a simple text string or a detailed configuration object with styling options.
---
nav:
badge: NEW
---
# Sample Page
---
nav:
# Shortcut pipe syntax for setting variant
badge: NEW|info
---
# Sample Page
---
nav:
badge:
text: BETA
variant: warning
icon: bell
iconAlign: right
corners: pill
size: s
---
# Sample Page
The badge supports all the same properties as the Badge component, including:
| Property | Type | Description |
|---|---|---|
text |
string |
The text content of the badge |
variant |
string |
Add Badge variants supported, including: base, primary (default), secondary, success, danger, warning, info, light, dark, ghost, contrast |
size |
string |
Badge size: xs, s, m, l, xl, 2xl, 3xl (default: s) |
corners |
string |
Badge corner style: round, square, pill |
icon |
string |
Icon name from UIcons or custom icon |
iconAlign |
string |
Icon position: left or right |
link |
string |
Page or URL to navigate to when badge is clicked |
target |
string |
Link target: blank, self, parent, top |
mode
mode : string
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.
| Option | Description |
|---|---|
default |
Create the navigation as a Tree structure where top-level folders are expandable and collapsible. |
stack |
Create the navigation where the top-level folders are automatically expanded, creating a "stacked" view of the navigation path. |
The nav.mode setting can be configured on any page within a top-level folder to convert only that specific folder into a "stack" navigation structure. The remaining top-level folders will maintain their default tree navigation behavior.
The following sample demonstrates how to configure the "stacked" navigation structure for a specific top-level folder:
nav:
mode: stack
When configured on a page within a top-level folder, this setting will only affect that specific folder's navigation structure.
To convert the entire navigation component to a stack type layout, please see the Project nav setting.
nextprev
The nextprev configuration controls the display of "Next" and "Previous" navigation buttons at the bottom of each page and whether a page is included in the navigation sequence.
mode
mode : string
Controls how the Next/Previous navigation buttons are displayed and whether the page is included in the navigation sequence.
| Option | Description |
|---|---|
show |
Show Next and Previous buttons and include page in sequence (Default) |
hide |
Hide buttons but keep page in sequential order |
exclude |
Hide buttons and exclude page from sequential order |
The default value is show.
---
nextprev:
mode: hide
---
order
order : string
A custom stack order for this page within the left side-bar tree navigation.
Options can include:
- A number such as
100or-100 - Any string value that will be slotted into the
A -> Zalpha ordering of all navigation nodes - A SemVer value such as
v2.0
If the order is set with a number, a larger positive number will give more weight or priority to that page and Neko will bubble up that page in the navigation. For instance, a page configured with order: 100 will be higher in the navigation than a page configured with order: 10.
Similarily, a page configured with order: -100 will be lower in the navigation than a page configured with order: -10 or any page where no order is set.
The position of folders within the navigation can be ordered as well using the same order technique, the only difference that folders are always pinned to the top of their order group.
In order of precedence, the order of a page in the navigation would be determined with the following priority:
| Value type | Description |
|---|---|
number (positive) |
A larger positive number gets more weight or priority and is pushed higher in the navigation. Largest number at the top. Example: order: 100 will be ordered above order: 10. |
alpha (high) |
Setting order with an alpha-numeric value is possible and those pages will be ordered against the label value of all other pages that do not have an order configured. Example: order: alpha will be ordered above order: beta or a page configured with label: bravo. |
no order set |
If no order is configured, all pages will be ordered alphabetically based on its label, title, the first h1 title, or the file name values. The label config has the highest priority. |
alpha (low) |
Example: order: zulu will be ordered below order: zebra or a page configured with label: yakee. |
vSemver (newer) |
Page order configured with a semver value are ordered with the newest version above an older version. These pages are also moved towards the bottom of the navigation. Example: order: v1.1 will be ordered above order: v1.0. |
number (negative) |
A negative number gets less weight or priority and is pushed to the bottom of the navigation. Setting the order with a negative number is a simple way to push a page to the bottom of the navigation. Example: order: -100 will be ordered below order: -10. |
By default, the home page of the website has an order of 10000. To add a page in the navigation just above the home page, set a value of order: 10001 or greater. To add a page in the navigation just below the home page, set a value of order: 9999 or lower. To move the home page to the bottom of the navigation, set a negative value, such as order: -10000.
Order by number
Larger number = order higher in the stack.
No order number or 0 = order by alpha
Smaller number = order lower in the stack.
If multiple pages have the same order number, secondary ordering in that cluster is by alpha.
+
0
-
Order by alpha
Order values by alpha.
a = higher
z = lower
Alpha
Bravo
Charlie
Zulu
Order by `v
Order by semver with latest release at the top
v5.0.1
v5
v4.0
v3.1
v3.0
v2.0
v1.0
Items prefixed with v would be grouped below the alpha ordered items.
alpha
bravo
yankee
zulu
v3.0
v2.1-beta
v2.0
v1.0
v1.0-beta
v1.0-alpha
password
password : string
Password-protect this specific page.
---
password: "your-secret-password"
---
When a visitor navigates to the page, they will be prompted to enter the password to unlock and view the content.
The content is encrypted at build time and decrypted in the browser using the password provided by the user.
See password protection for more details.
permalink
permalink : string
A custom URL path for this page or folder which overrides the default path generated by Neko.
---
permalink: /custom/path
---
# My page title
Some content here.
A permalink allows the folder and file structure to remain unchanged, but allowing the final URL's to be customized.
Configuring the permalink is an excellent solution when moving to Neko from another platform and you would like to maintain existing public URL's, but would prefer to re-organize your .md files into a new structure. A permalink allows for a clean disconnect of the page path from the final published URL path.
In the following sample, the generated URL by Neko would be /guide/2021-06-25-publishing-to-github-pages/, but we override with a custom permalink which will publish the page to /tutorial/publish-to-github-pages/.
---
permalink: /tutorial/publish-to-github-pages/
---
# Publishing to GitHub Pages
If a permalink is configured on a folder, or on a readme.md or index.md page within the folder, or on an index.yml file within the folder, that permalink is assumed to be the base permalink for all pages within that folder.
The following scenario demonstrates a basic scenario where we configure all pages within the /guides/ folder to be served from the custom URL location of /tutorials/.
To accomplish this goal, configure the permalink on the readme.md, then all other pages within the same folder will adjust as well. The configuration.md page will now be served from /tutorials/configuration/.
|-- /guides
|-- readme.md
|-- configuration.md
---
permalink: /tutorials
---
# Tutorials
| File path | Old URL | New URL |
|---|---|---|
/guides/readme.md |
/guides |
/tutorials |
/guides/configuration.md |
/guides/configuration |
/tutorials/configuration |
redirect
redirect : string
Redirect requests for this page to another location.
The redirect can be set to another page within this project, or an external link.
For example, you have an existing setup.md page and you want to move the content to getting-started.md, but other websites might still be linking to your old example.com/setup/ page and you want to ensure those links still work. You would then set the following redirect page config in setup.md to redirect to getting-started.md.
---
redirect: getting-started.md
---
# Setup
Neko will automatically handle any incoming example.com/setup requests and redirect to the new example.com/getting-started location.
Neko is also smart enough to scan your project for any setup.md links and replace those with a link directly to getting-started.md.
route
See permalink.
tags
tags : list
A list of tags can be added to the metadata at the top of each .md page you would like to tag.
The tags are meant to describe specific details of the content in that page. Tags are similar to category, although category is meant to describe be a broad grouping of content. A page can belong to multiple (zero to many) categories and have multiple (zero to many) tags.
If tags are configured in the page metadata, a list of tag links are added to the bottom of the page. See the bottom of this page for a working sample.
Individual tag summary pages will be automatically generated by Neko at <url>/tags/<tag>, plus an additional <url>/tags index page which lists all tags and their count used within the project.
Check out the pages of this website configured with the guide tag.
---
tags: [guide]
---
# Page title
Some content here.
Multiple tags can be added to the list by separating each with a comma ,.
---
tags: [guide, config options, installation]
---
# Page title
Some content here.
A list style syntax is also supported for tags:
---
tags:
- guide
- config options
- installation
---
target
target : string
Controls how navigation links to this page behave when clicked in the sidebar navigation tree.
---
target: blank
---
# External Documentation
This page will open in a new tab when clicked in the navigation.
Supported values:
| Value | Transformed To | Description |
|---|---|---|
blank |
_blank |
Opens the link in a new tab |
self |
_self |
Opens the link in the current tab (default) |
parent |
_parent |
Opens the link in the parent frame |
top |
_top |
Opens the link in the top-most frame |
Neko automatically transforms common values like blank to _blank.
This setting is useful when a page redirects to an external location, allowing new tabs to open without losing the current documentation context.
---
title: API Reference
redirect: https://api.example.com/docs
target: blank
---
templating
templating: boolean
Templating can be disabled on a per-page basis by setting templating: false in the page metadata.
---
templating: false
---
title
title : string
The title config instructs Neko to add a primary # Page Title to your page, but it is recommended to manually add a # Page Title to each of your pages, instead of setting a title.
As a general rule, the actual content of your page should not be configured in the page metadata.
The title is primarily used to support backwards compatibiity with the .md content style from other older legacy static site generator applications.
The following sample demonstrates setting the title config instead of explicitly using a # Page Title to your page.
---
title: Getting Started
---
Some content here.
Try to avoid using the title config. Please add a real page # Page Title to your document. The # Page Title will be rendered in HTML as <h1>Page Title</h1>.
For example, the sample above should ideally be written as the following instead of using a title config.
# Getting Started
Some content here.
toc
The toc config contains page options that apply to the right sidebar Table of Contents.
depth
depth : string, number
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 Page or Project levels.
Configuring the toc at the Page level overrides the Project level settings.
Acceptable values for depth include:
| Value | Description |
|---|---|
| 2 | Include H2 headings only |
| 2-3 | default Include H2 to H3 headings |
| 1-4 | Include H1 to H3 headings |
| 2,3 | Include H2 and H3 headings |
| 2,4 | Include H2 and H4 headings |
| 1,3-4 | Include H1 and H3 to H4 headings, skip H2 |
| 1,2,3,4 | Include H1, H2, H3, and H4 headings |
label
label : string
A custom label for the top of the Table of Contents column.
toc:
label: On this page
visibility
visibility : public|hidden|protected|private
Configure the visibility of the page to be public, hidden, protected, or private. Default is public.
| Mode | Navigation | Search | Password | Description |
| --- | | | | --- |
public | | | | The page is public and visible in the main navigation. A password is not required to view this page.
hidden | | | | The page will not be included in the navigation or search results, and a password is NOT required to view the page. This visibility is helpful for sharing a draft page before exposing the page to be public (sample).
protected | | | | The page is added to the public navigation but requires a password to access the content of the page (sample password: test).
private | | | | The page is hidden, not added to the navigation, and a password is required for access (sample password: test).
hidden
With hidden, the page will still be created and added to the final website, but it is hidden. You can still link to the page or share a link to the page.
Neko would ensure no automatically generated links or references to the hidden page are created. If on a public page, a link to a hidden page is made by an author, the link will work and the hidden page will be visible.
The following sample demonstrates hiding a page:
---
visibility: hidden
---
# A hidden page
This page will be hidden from the menu and search results.
The History component will continue to function as normal. Any hidden page visited would still be logged in the history, although that history is only available to the visitor.
Setting visibility: hidden on a page is a good way to create a draft or secret page that you do not want included in the navigation, but you still want to share a link to the page for others to view if they have the link.
protected
To create a protected page, add visibility: protected and then set the password for the project using the --password flag.
The following sample (password: test) demonstrates creating a protected page:
---
visibility: protected
---
# A protected page
This page will be visible in the main navigation, but will require a password to view the page.
Then call either of the following commands to set the password for the project:
neko start --password <your-password>
neko build --password <your-password>
An entire folder can be set to protected by adding an index.yml file with the following configuration to the root of the folder. See the folder docs for additional examples.
visibility: protected
private
To create a private page, add visibility: private and then set the password for the project using the --password flag.
The following sample (password: test) demonstrates creating a private page:
---
visibility: private
---
# A private page
This page will not be visible in the main navigation and will require a password to view the page.
Then call either of the following commands to set the password for the project:
neko start --password <your-password>
neko build --password <your-password>
For hidden and private pages, Neko does not provide a link to the page, but it still uses the same naming convention as all other pages. For instance, if your site is hosted at https://example.com and the page was called my-hidden-page.md, the URL would be https://example.com/my-hidden-page/.
An entire folder can be set to private by adding an index.yml file with the following configuration to the root of the folder. See the folder docs for additional examples.
visibility: private