simplest-sitegen

v0.13.1

Published

2 years ago

The simplest static sitegen there is. Build a modern, fully working website with only HTML.

Downloads

0High
0Medium
0Low

ciscoheat

static-site-generator static-site ssg website generator html

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

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title><!-- build:title --></title>
    <link rel="stylesheet" href="/style.css">
    <!-- build:styles -->
  </head>
  <body>
    <!-- build:content -->
    <!-- build:scripts -->
  </body>
</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

<!-- build:title -->Simplest<!-- /build:title -->
<!-- build:content -->
<h1>The simplest site generator is finally here!</h1>
<!-- /build:content -->

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

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 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 instead of css in your html files. It's a ridiculously simple drop-in replacement in your html:

<link rel="stylesheet" href="/style.scss">

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 is a template language in the spirit of simplicity, so yes, it can be used:

src/index.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 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

<script>
  export const title = "Simplest"
</script>

<h1>The simplest site generator is finally here!</h1>

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:

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
Sass options are listed here
Markdown-it options are listed here
Pug options are listed here
Glob patterns are available here.

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

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

<!-- build:title -->PHP Powered site!<!-- /build:title -->
<!-- build:content -->
<h1>PHP test</h1>
<ul>
<?php foreach(array("A", "B", "C") as $char): ?>
  <li><b><?php echo $char ?>:</b> Php works</li>
<?php endforeach; ?>
</ul>
<!-- /build:content -->

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 or Astro.

If your site is mostly static but you want a more complete CMS/blog with advanced templating, look at the jamstack 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.

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 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.

Thanks for reading, and enjoy simplicity for a change!

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

simplest-sitegen

No scaffolding except one file: src/template.html

Building the site

It has a Dev server, of course

Multiple templates

Cache busting included

Extra features

Sass

Markdown

Pug

Svelte!

Configuration

Server-side power with PHP

When not to use Simplest

If you dislike scaffolding

Feedback wanted

No scaffolding except one file: `src/template.html`