{"id":18277730,"url":"https://github.com/ctnicholas/keystone-ssg","last_synced_at":"2025-04-05T04:30:46.128Z","repository":{"id":39626889,"uuid":"270656378","full_name":"CTNicholas/keystone-ssg","owner":"CTNicholas","description":"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.","archived":false,"fork":false,"pushed_at":"2023-03-05T05:21:02.000Z","size":1131,"stargazers_count":8,"open_issues_count":19,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-20T21:44:28.589Z","etag":null,"topics":["babel","devserver","keystone","keystone-ssg","markdown","nodejs","rollup","routing","scss","ssg","static-site","static-site-generator"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CTNicholas.png","metadata":{"files":{"readme":"README.MD","changelog":"CHANGELOG.MD","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-06-08T12:16:00.000Z","updated_at":"2023-08-06T06:30:05.000Z","dependencies_parsed_at":"2023-02-05T23:16:47.906Z","dependency_job_id":null,"html_url":"https://github.com/CTNicholas/keystone-ssg","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTNicholas%2Fkeystone-ssg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTNicholas%2Fkeystone-ssg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTNicholas%2Fkeystone-ssg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CTNicholas%2Fkeystone-ssg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CTNicholas","download_url":"https://codeload.github.com/CTNicholas/keystone-ssg/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289382,"owners_count":20914463,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","devserver","keystone","keystone-ssg","markdown","nodejs","rollup","routing","scss","ssg","static-site","static-site-generator"],"created_at":"2024-11-05T12:20:25.150Z","updated_at":"2025-04-05T04:30:44.107Z","avatar_url":"https://github.com/CTNicholas.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Warning\n\nKeystone is looking outdated these days, I'd recommend you take a look into [Astro](https://astro.build/) or [Vite](https://vitejs.dev/) instead.\n\n---\n\n\u003cbr /\u003e\n\n![Keystone logo](https://github.com/CTNicholas/keystone-ssg/raw/master/keystone_logo_small.png)\n# Why Keystone?\nKeystone is a static-site generator ideal for quickly building small websites. No setup required, and a collection of handy features are enabled by default.\n# Features\n- Easy install \u0026 setup, one command and ready to go\n- Auto-refresh development server\n- Use templates and reusable partials/imports, with slots\n- Automatic routing, just upload `/public` and you're ready to go\n- Babel, SCSS, \u0026 Markdown support enabled by default, source maps in development mode\n- JS \u0026 CSS minifying and bundling (with Rollup)\n- Dynamic link loading (no page reload)\n- Search index file generator, for easy website searching\n\n# Getting Started\n## Install\nCreate a new directory and run the following command to setup Keystone, package.json, \u0026 git. *Node 14.x.x required.*\n```\n$  npm install keystone-ssg\n```\nGreat, you're installed!\n## Development server\nStart the Keystone development server, and then go to http://localhost:8080 to see the example website.\n```\n$ npm run dev\n```\n## Build project\nThe project is built within the `/public` folder after running the command, ready for upload.\n```\n$ npm run build\n```\n# Building your website\nThere are six important directories within a Keystone project, each with their own purpose:\n\n## Pages\nEvery HTML `.html` \u0026 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:\n```\n/pages/index.html   -\u003e  /public/index.html\n/pages/example.md -\u003e  /public/example/index.html\n```\nYou may have noticed that `index.html` has the following tag: `\u003c_template basic.html /\u003e`. 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.\n## Templates\nTemplates can be used with `/pages` to provide a ready-made framework for your pages. Use a `\u003c_slot /\u003e` tag within the template file to provide an entry point for your content. Open `/templates/basic.html` and look for:\n```html\n\u003c_var title default=\"Keystone default title\" /\u003e\n```\nThis is a variable slot, named `title`, in a template file, with an optional default value. \n\nUsing the following as a template tag inside of `/pages` will allow you to enter a custom value into the template, from a content page:\n```html\n\u003c_template basic.html title=\"A custom title\" /\u003e\n```\n## Components\nThe `/components` folder is simply used for reusable components. The `\u003c_import\u003e` tag is used to import components into other HTML files, an example of which is inside `/templates/basic.html`.\n```html\n\u003c_import header.html /\u003e\n```\nThe `\u003c_import\u003e` tag can also be used to import the contents of any other kind of file (JS, SCSS etc), after first bundling the source.\n## Src\nPlace Javascript files within the `/src` folder. The following tag will be converted to a regular `\u003cscript\u003e` import tag, linking to your file `/src/main.js`:\n```html\n\u003c_script main.js /\u003e\n```\nES6 imports are fully supported, and the resulting file will be transpiled with Babel, bundled with Rollup, and minified.\n## Styles\nThe `/styles` folder is used for your CSS/SCSS. The following tag will be converted to a regular `\u003clink\u003e` css import tag, linking to your compiled `/styles/main.scss` file:\n```html\n\u003c_style main.scss /\u003e\n```\nAll `node-sass` features are fully supported, including `@import`.\n## Assets\nStatic assets are placed here, ie fonts, images, icons. Everything here will be transferred to it's corresponding folder in the root directory, for example:\n```\n/assets/favicon.ico -\u003e /public/favicon.ico\n/assets/fonts/fontname.ttf -\u003e /public/fonts/fontname.ttf\n```\n# Notes\n## Keystone HTML tags\n- Every custom Keystone HTML tag can be used *anywhere* within an HTML file, even within other HTML attributes, apart from in other Keystone tags.\n- For all custom Keystone tags, alternatively, you can use a src attribute to target a file in any folder: `\u003c_template src='myfolder/myfile.html' /\u003e`. \n- 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.\n- Keystone HTML tag attributes can use 'single' \"double\" or \\`backtick\\` quote marks.\n## Dynamic loading\n- Dynamic loading fetches the local website link and replaces the content of the current page with the new page, without reloading and switching pages.\n- While dynamic loading is enabled, page state (eg input values, scroll position) is not saved when using the back button.\n- 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.\n- Disable dynamic loading in keystone.config.js.\n## Search index generator\n- 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.\n- All HTML tags are stripped from the page, and only the text is kept and stored.\n- This file can be fetched and queried be a website search function, to easily find which page contains which content.\n- Disable the search bar helper in keystone.config.js.\n## Miscellaneous\n- The `public` folder is ignored by Git, remove the `public` line from `.gitignore` should you wish to use to commit it to Git.\n## Updating Keystone\n- Replace the version number in `package.json` with the version you're updating to and run `npm install keystone-ssg`, for a quick upgrade.\n\n\n# API\n## Tags\nTag | Description | Attributes\n-|-|-\n`\u003c_template\u003e` | Imports the current file into a `\u003c_slot\u003e` within the template file | [file name], [variable name], src\n`\u003c_slot\u003e` | Used within a template file as an entry point for the imported file | *None*\n`\u003c_var\u003e` | Used within a template file to be replaced by a variable taken from `\u003c_template\u003e` | [variable name], default\n`\u003c_import\u003e` | Imports a component | [file name], src\n`\u003c_script\u003e` | Creates a `\u003cscript\u003e` tag linking to the bundled script | [file name], src\n`\u003c_style\u003e` | Creates a `\u003clink\u003e` tag linking to the bundled css file | [file name], src\n\n## NPM Commands\nCommand | Description | Output differences\n-|-|-\n`npm run dev` | Builds the website for development, then starts the Keystone development server. | \u003cul\u003e\u003cli\u003eInline source maps are generated.\u003c/li\u003e\u003cli\u003eDevelopment server script is injected.\u003c/li\u003e\u003c/ul\u003e\n`npm run build` | Builds the website for production. | \u003cul\u003e\u003cli\u003eBundle is compacted \u0026 minified.\u003c/li\u003e\u003c/ul\u003e\n\n## Config file\nThe config file is `keystone.config.js`\nOption | Description | Default\n-|-|-\ndynamicLinks | Enables dynamically loaded local links on your Keystone website, no refresh needed | true\nsearchFile | Generates `search.json` in the root directory | true\nindexPath | The root directory of your website | '/'\nport | The dev server port, localhost:**8080** | 8080\nportWs | A second port used for the dev server | 8081\ndevServerIp | 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'\nwatched | 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']\nbuild | The content page directory | 'pages'\nserved | The directory containing the generated website | 'public'\nfullRecompile | Force a full recompile of all files after each file change in development mode | false\n\n## Default directory layout\n```\n| empty-keystone-project\n--| .git/\n--| assets/\n--| components/\n--| pages/\n--| src/\n--| styles/\n--| templates/\n--| keystone.config.js\n--| package.json\n--| package-lock.json\n```\n\n## Plugin error\nIf you have a PLUGIN_ERROR after installing and running the example, this is a Babel problem, run the following command to fix it:\n```\nnpm install @babel/core @babel/preset-env --save-dev\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctnicholas%2Fkeystone-ssg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fctnicholas%2Fkeystone-ssg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fctnicholas%2Fkeystone-ssg/lists"}