Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ciscoheat/simplest-sitegen
The simplest static sitegen there is. Build a modern, fully working website with only HTML.
https://github.com/ciscoheat/simplest-sitegen
html jamstack sitegen static-site-generator
Last synced: 2 days ago
JSON representation
The simplest static sitegen there is. Build a modern, fully working website with only HTML.
- Host: GitHub
- URL: https://github.com/ciscoheat/simplest-sitegen
- Owner: ciscoheat
- Created: 2022-08-21T23:31:10.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2022-09-27T07:18:41.000Z (about 2 years ago)
- Last Synced: 2024-09-15T15:24:55.449Z (12 days ago)
- Topics: html, jamstack, sitegen, static-site-generator
- Language: HTML
- Homepage: https://www.npmjs.com/package/simplest-sitegen
- Size: 609 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# simplest-sitegen
**Simplest** is the simplest static sitegen you can find, while still being quite able. It's perfect for smaller websites with just a little dynamic content, and when you want something up fast without diving deep into documentation.
The bold claim of being simplest is made because only HTML is needed. No markdown, no yaml, no template languages, no huge documentation, and a one-step build process. Create a new project with it immediately:
```
npm create simplest-sitegen
```
## No scaffolding except one file: `src/template.html`
That's right, there won't be fifteen files in your project after running a cryptic package command. The only file you need is `src/template.html`, which is the template that your other html files will be based on. Open it up in your editor of choice. It will look similar to this:
**src/template.html**
```html
```
There are four template variables inside it, only one is required: ``
Now let's build the real site content, why not the index page:
**src/index.html**
```html
Simplest
The simplest site generator is finally here!
```
It's just HTML! No need to learn anything, since you already know it!
Lets just add a little bit of style though:
**src/style.css**
```css
h1 {
color: #6200EE;
}
```
## Building the site
```
cd new-project
npx simplest build
```
This will generate your brand new site in the `build` directory, that can be uploaded directly to any host. For more pages and files, just add them in `src` in any folder structure, and they will be copied over to the correct dir.
It's up to you to link to them correctly, create a nice navigation in `template.html`, etc, but that's quick and easy compared to plowing through the documentation of any other "simpler" site generator out there. Just include your favorite css framework, and you should be good to go.
## It has a Dev server, of course
Simplest near-real time hot-reloading dev server is one of the simplest to use:
```
npx simplest
```
This will start a [Browsersync](https://browsersync.io/) server, and open up a browser window for you. Any changes in `src` will update the browser automatically.
## Multiple templates
You can put a `template.html` in any subdirectory, and all html files in that directory and below will use that template instead of the top-level one.
## Cache busting included
All links, scripts and images relative to the site, for example `/script.js` or `../css/style.css` (but not `https://example.com/script.js`), will be automatically cache-busted, so you don't have to worry about serving old content. You will also get a warning if a file doesn't exist.
# Extra features
If you're fine with HTML and nothing else, the above is all you need to know. Go and create something beautiful!
But if you're comfortable with web development, there are libraries and tools that makes life easier. Simplest includes some of them. They are purely optional.
## Sass
You can use [Sass](https://sass-lang.com/) instead of css in your html files. It's a ridiculously simple drop-in replacement in your html:
```html
```
Just make sure that the source file is in the correct directory as the output, i.e. `src/css/style.scss` should be linked as `/css/style.scss` in the template.
## Markdown
Markdown is simple enough for it to be included. This is the corresponding `.md` file for the index page in the example above:
**src/index.md**
```
---
title: Simplest
---
# The simplest site generator is finally here!
```
Just be aware that it's unspecified which file will take precedence when only the extension differ. So having an `index.html` in the same directory as `index.md` will probably cause trouble. A warning will be issued if that's the case.
## Pug
[Pug](https://pugjs.org/) is a template language in the spirit of simplicity, so yes, it can be used:
**src/index.pug**
```pug
- const title = "Simplest"
h1 The simplest site generator is finally here!
```
Any top-level unbuffered code (a line starting with `-`) will be parsed into a corresponding `` comment block.
## Svelte!
Using [Svelte](https://svelte.dev/) components is far from keeping things simple, right? Well, if you're looking for some sporadic client-side interactivity, a Svelte component makes things quite simple. Here's the start page representation:
**src/index.svelte**
```svelte
export const title = "Simplest"
The simplest site generator is finally here!
```
All **export const** variables will be used in the template. Unfortunately there cannot be any nested components. The reason is technical, but let's say for now that nested components wouldn't be simple enough. :)
## Configuration
If you need to complicate things, it's understandable, things aren't always as simple as one would like. Fortunately it's not too hard to configure simplest. Create a `simplest.config.js` file in your project top directory, with any of the following properties:
```js
export default {
input: "src",
output: "build",
template: "template.html", // Template file(s) to look for
htmlExtensions: [".html", ".htm"], // What files to parse for HTML content
sourceExtensions: [".sass", ".scss", ".pug", ".svelte"], // Won't be copied to the output dir
passThrough: [], // Glob patterns (relative to input dir) that will skip parsing
devServerOptions: { ui: false, notify: false }, // Extra Browsersync options
sassOptions: { style: "compressed" }, // Extra sass options
markdownOptions: {}, // Extra markdown-it options
pugOptions: {}, // Extra pug options
plugins: [], // Will be documented on popular request
verbose: false
}
```
- Browsersync options are listed [here](https://browsersync.io/docs/options)
- Sass options are listed [here](https://sass-lang.com/documentation/js-api/interfaces/Options)
- Markdown-it options are listed [here](https://www.npmjs.com/package/markdown-it#init-with-presets-and-options)
- Pug options are listed [here](https://pugjs.org/api/reference.html)
- Glob patterns are available [here](https://github.com/mrmlnc/fast-glob#pattern-syntax).
## Server-side power with PHP
The easiest and cheapest way to add powerful server-side capabilities to Simplest is by parsing PHP files, using the built-in PHP dev server to keep the hot reload capabilities. Configure it like this:
**simplest.config.js**
```js
export default {
htmlExtensions: [".html", ".htm", ".php"],
devServerOptions: {
ui: false, notify: false,
server: undefined,
proxy: "127.0.0.1:3500"
}
}
```
Then start the `php` dev server (make sure [PHP is installed](https://www.php.net/downloads.php) on your system first):
```
php -S 127.0.0.1:3500 -t build
```
With this, you can start using PHP files! Start `npx simplest` to confirm that the Browsersync proxy works, then replace `src/index.html` with this file to test:
**src/index.php**
```php
PHP Powered site!
PHP test
-
: Php works
```
If you want to add a PHP framework to the site, exclude it from parsing using the `passThrough` configuration option.
## When not to use Simplest
When your site is more dynamic and data-driven, and you want routing, client-side rendering, etc, you're better of using [SvelteKit](https://kit.svelte.dev/) or [Astro](https://astro.build/).
If your site is mostly static but you want a more complete CMS/blog with advanced templating, look at the [jamstack generators](https://jamstack.org/generators/) again.
But for non-complicated sites where a directory based structure is adequate, Simplest should be fine, and you can even add some CMS capabilities with a [headless CMS](https://jamstack.org/headless-cms/).
## If you dislike scaffolding
Here's how to create a project manually:
```
mkdir new-project
cd new-project
npm init
npm i simplest-sitegen
mkdir src
```
([pnpm](https://pnpm.io/) is recommended instead of npm though!)
Then add `"type": "module"` to your `package.json` file. Finally, create a `src/template.html` file and you're ready to go.
## Feedback wanted
Comments, bug reports and feature requests that will keep things simple(st), are very welcome as a [github issue](https://github.com/ciscoheat/simplest-sitegen/issues).
Thanks for reading, and enjoy simplicity for a change!