Reserved words
There are several folder and file names within a Neko project that incorporate special behaviour and are considered reserved words.
All paths to folders or files within Neko are relative to your project input directory.
Folders
/blog
The /blog folder is intended to host a Blog for your website.
By default, .md pages created within the /blog folder are assigned the layout: blog layout, plus some additional features:
- A summary page of the blog posts is automatically created at
/blog. - An RSS feed of the recent blog posts is created.
- Blog pages get
NewerandOlderbuttons at the bottom of each page. - All blog pages are set with the
layout: bloglayout, unless otherwise specified in the page metadata.
/categories
The default index page of the /categories directory is reserved for a summary of any category configs. Every category configured within an .md page of your Neko project will have a corresponding entry here.
Similar to /tags, you can also add content to the /categories page by creating your own /categories/index.md page. Neko will create your page as normal and then add the list of Categories below your custom content.
/resources
Any files placed within this directory will be copied to the output directory. Please see the include and exclude configs for fine-grained control over including or excluding files or folders.
/tags
The /tags directory is reserved for tags. Every tag name configured within an .md page will have a corresponding entry here.
Similar to /categories, you can also add content to the /tags page by creating your own /tags/index.md page. Neko will create your page as normal and then add the list of Tags below your custom content.
Files
CNAME
A CNAME file will be automatically created if the url is configured with a domain name or subdomain.
For instance, including url: docs.example.com within your neko.yml project config file also instructs Neko to create a CNAME file with the value docs.example.com. That CNAME file is used by GitHub Pages and possibly other website hosting services as the way to configure custom domain name hosting.
If you manually create a CNAME file within the root of the input folder of your project, Neko will not automatically create the CNAME file, even if the url or cname is configured or conflicts.
Default pages
Project config
By default, if you do not pass an explicit project configuration file name in the <path> command line argument, Neko will search for your project config using the following case insensitive priority:
neko.ymlneko.yamlneko.json
For instance, if you run the CLI command neko start docs, Neko will first try to find the project configuration file docs/neko.yml. If not found, then docs/neko.yaml will be tested and so on.
If you run the command neko start docs/neko.json, even if a neko.yml is present, Neko will only read the neko.json file as you are explicitly passing the project configuration file path.
Custom project config file names are also possible by explicitly passing a file name, such as neko start docs.yml. Where docs.yml is used instead of neko.yml, even if neko.yml is present.
Once a project configuration file is found, it is used. If the other files are found, they are ignored. Neko will not merge or override different configs or conflicting configs between two or more project files.