#
Reserved words
There are several folder and file names within a Retype project that incorporate special behaviour and are considered reserved words.
All paths to folders or files within Retype 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
Newer
andOlder
buttons at the bottom of each page. - All blog pages are set with the
layout: blog
layout, 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 Retype project will have a corresponding entry here.
Similar to /tags
/categories
page by creating your own /categories/index.md
page. Retype 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
/tags
page by creating your own /tags/index.md
page. Retype 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 or sub-domain.
For instance, including url: docs.example.com
within your retype.yml
project config file also instructs Retype 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, Retype will not automatically create the CNAME
file, even if the url
or cname
is configured or conflicts.
#
Default pages
Folder default pages are custom .md
files that will be treated as the index page of the folder.
Retype will search using the following case insensitive priority:
index.md
readme.md
default.md
For instance, creating a the file docs/index.md
will create a custom page accessible from the path https://example.com/docs/
. The index.md
page instructs Retype to create an index.html
file within the docs/
folder.
#
Project config
By default, if you do not pass an explicit project configuration file name in the <path>
command line argument, Retype will search for your project config using the following case insensitive priority:
retype.yml
retype.yaml
retype.json
For instance, if you run the CLI command retype watch docs
, Retype will first try to find the project configuration file docs/retype.yml
. If not found, then docs/retype.yaml
will be tested and so on.
If you run the command retype watch docs/retype.json
, even if a retype.yml
is present, Retype will only read the retype.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 retype watch docs.yml
. Where docs.yml
is used instead of retype.yml
, even if retype.yml
is present.
Once a file is found, it is used. If the other files are found, they are ignored. Retype will not merge or override different configs or conflicting configs between two or more project files.