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.
- 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
/publicand 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
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!
Start the Keystone development server, and then go to http://localhost:8080 to see the example website.
$ npm run dev
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:
.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 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 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
<_import header.html />
<_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 folder. The following tag will be converted to a regular
<script> import tag, linking to your file
<_script main.js />
ES6 imports are fully supported, and the resulting file will be transpiled with Babel, bundled with Rollup, and minified.
/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
<_style main.scss />
node-sass features are fully supported, including
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
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 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-loadingclass is set to
display: block. If the class is set to
display: nonein 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.
publicfolder is ignored by Git, remove the
.gitignoreshould you wish to use to commit it to Git.
- Replace the version number in
package.jsonwith the version you're updating to and run
npm install keystone-ssg, for a quick upgrade.
||Imports the current file into a
||[file name], [variable name], src|
||Used within a template file as an entry point for the imported file||None|
||Used within a template file to be replaced by a variable taken from
||[variable name], default|
||Imports a component||[file name], src|
||[file name], src|
||[file name], src|
||Builds the website for development, then starts the Keystone development server.||
||Builds the website for production.||
The config file is
|dynamicLinks||Enables dynamically loaded local links on your Keystone website, no refresh needed||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
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