Building your website

There are six important directories within a Keystone project, each with their own purpose:

Pages

Every HTML .html & markdown .md file in the pages folder corresponds to a page on your website. There are two files in the example project in here, try opening index.html. The automatic routing will bundle the files to the /public folder upon running npm run build like so:

/pages/index.html   ->  /public/index.html
/pages/example.md ->  /public/example/index.html

You may have noticed that index.html has the following tag: . This places the contents of index.html inside the slotted template file at /templates/basic.html. This custom HTML tag format works inside .md files too.

Templates

Templates can be used with /pages to provide a ready-made framework for your pages. Use a <_slot /> tag within the template file to provide an entry point for your content. Open /templates/basic.html and look for:

Keystone default title

This is a variable slot, named title, in a template file, with an optional default value.

Using the following as a template tag inside of /pages will allow you to enter a custom value into the template, from a content page:

Components

The /components folder is simply used for reusable components. The <_import> tag is used to import components into other HTML files, an example of which is inside /templates/basic.html.

<_import header.html />

The <_import> tag can also be used to import the contents of any other kind of file (JS, SCSS etc), after first bundling the source.

Src

Place Javascript files within the /src folder. The following tag will be converted to a regular <script> import tag, linking to your file /src/main.js:

ES6 imports are fully supported, and the resulting file will be transpiled with Babel, bundled with Rollup, and minified.

Styles

The /styles folder is used for your CSS/SCSS. The following tag will be converted to a regular <link> css import tag, linking to your compiled /styles/main.scss file:

All node-sass features are fully supported, including @import.

Assets

Static assets are placed here, ie fonts, images, icons. Everything here will be transferred to it's corresponding folder in the root directory, for example:

/assets/favicon.ico -> /public/favicon.ico
/assets/fonts/fontname.ttf -> /public/fonts/fontname.ttf

Notes

Keystone HTML tags

• Every custom Keystone HTML tag can be used anywhere within an HTML file, even within other HTML attributes, apart from in other Keystone tags.
• For all custom Keystone tags, alternatively, you can use a src attribute to target a file in any folder: .
• All paths are relative to the folder containing package.json, do not use an initial slash unless you'd like to access a file outside of the project.
• Keystone HTML tag attributes can use 'single' "double" or `backtick` quote marks.

  Dynamic loading

• Dynamic loading fetches the local website link and replaces the content of the current page with the new page, without reloading and switching pages.
• While dynamic loading is enabled, page state (eg input values, scroll position) is not saved when using the back button.
• Disable dynamic loading in keystone.config.js.

  Search index generator

• The search index generator generates a file, search.json, in the root directory This is a JSON array containing an object for each page, listing the text content, title, and path of the page.
• All HTML tags are stripped from the page, and only the text is kept and stored.
• This file can be fetched and queried be a website search function, to easily find which page contains which content.
• Disable the search bar helper in keystone.config.js.