Why Keystone?

Keystone is a static-site generator ideal for quickly building small websites. No setup required, and a collection of handy features are enabled by default.

Features

• Easy install & setup, one command and ready to go
• Auto-refresh development server
• Use templates and reusable partials/imports, with slots
• Automatic routing, just upload /public and you're ready to go
• Babel, SCSS, & Markdown support enabled by default, source maps in development mode
• JS & CSS minifying and bundling (with Rollup)
• Dynamic link loading (no page reload)
• Search index file generator, for easy website searching

Getting Started

Install

Create a new directory and run the following command to setup Keystone, package.json, & git. Node 14.x.x required.

$  npm install keystone-ssg

Great, you're installed!

Development server

Start the Keystone development server, and then go to http://localhost:8080 to see the example website.

$ npm run dev

Build project

The project is built within the /public folder after running the command, ready for upload.

$ npm run build

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: <_template basic.html />. 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:

<_var title default="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:

<_template basic.html title="A custom title" />

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:

<_script 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:

<_style main.scss />

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: <_template src='myfolder/myfile.html' />.
• 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.
• When a link is clicked, the .keystone-page-loading class is set to display: block. If the class is set to display: none in the CSS, this can be used to create a loading indicator.
• 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.

Miscellaneous

• The public folder is ignored by Git, remove the public line from .gitignore should you wish to use to commit it to Git.

Updating Keystone

• Replace the version number in package.json with the version you're updating to and run npm install keystone-ssg, for a quick upgrade.

API

Tags

Tag | Description | Attributes -|-|- <_template> | Imports the current file into a <_slot> within the template file | [file name], [variable name], src <_slot> | Used within a template file as an entry point for the imported file | None <_var> | Used within a template file to be replaced by a variable taken from <_template> | [variable name], default <_import> | Imports a component | [file name], src <_script> | Creates a <script> tag linking to the bundled script | [file name], src <_style> | Creates a <link> tag linking to the bundled css file | [file name], src

NPM Commands

Command | Description | Output differences -|-|- npm run dev | Builds the website for development, then starts the Keystone development server. | Inline source maps are generated.Development server script is injected. npm run build | Builds the website for production. | Bundle is compacted & minified.

Config file

The config file is keystone.config.js Option | Description | Default -|-|- dynamicLinks | Enables dynamically loaded local links on your Keystone website, no refresh needed | true searchFile | Generates search.json in the root directory | true indexPath | The root directory of your website | '/' port | The dev server port, localhost:8080 | 8080 portWs | A second port used for the dev server | 8081 devServerIp | The location of the dev server, localhost:8080. Replace with your device's local IP to view dev server on local devices (example: '192.168.1.103'). | 'localhost' watched | The directories watched by the Keystone dev server, that will force a recompilation and page refresh when files are edited | ['templates', 'pages', 'assets', 'components', 'src', 'styles'] build | The content page directory | 'pages' served | The directory containing the generated website | 'public' fullRecompile | Force a full recompile of all files after each file change in development mode | false

Default directory layout

| empty-keystone-project
--| .git/
--| assets/
--| components/
--| pages/
--| src/
--| styles/
--| templates/
--| keystone.config.js
--| package.json
--| package-lock.json

Plugin error

If you have a PLUGIN_ERROR after installing and running the example, this is a Babel problem, run the following command to fix it:

npm install @babel/core @babel/preset-env --save-dev