Table of Contents
- Installation
- Example
- How does it work?
- API Documentation
- Plugins
- Development Setup
- How does it compare?
- What dependencies does it have?
- License
- extremely simple: the API exposes one function!
- easy to understand: only ~200 SLOC!
- very modern: works very well with async functions (node 7.6+)
- extendable as h*ck: provides hooking mechanisms to serve your every need
You need Node.js 7.6 or higher.
npm install --save @weh/weh
Let's write a simple program that changes the content of all files in a directory to "hey, what's up":
const weh = require('@weh/weh')
// this is this simplest plugin you can build!
// conveniently, plugins are just normal functions
const plugin = () => {
return files => {
// replace all file contents with the string
return files.map(file => Object.assign(file, {contents: 'hey, what\'s up'}))
}
}
// enter our main function:
// the main function should be an async function so that
// it automatically returns a promise
weh(async site => {
// we register our plugin...
site.use(plugin)
// ...and initiate the build process
return site
})
That's 8 lines of code!
Let's save this as example.js
. To run it, you need Node.js version 7.6 or
higher. The latest stable version will work.
node example.js
weh
doesn't output logs by default. If you want logs
(for example, for debugging), you can set the DEBUG
environment variable to:
weh # for base logs
weh:read # for specific read logs
weh:write # for specific write logs
# you can also combine any of the three
weh,weh:read
To get all logs at once, you can just set the variable to weh*
.
DEBUG=weh* node my_script # full logging!
weh
plugins may implement logging with different DEBUG
names.
It's fairly simple! What weh
does can be split up into two things:
- First, it reads a directory and saves all of the information about each file
into a gigantic object. That object can be manipulated by plugins, which
makes
weh
actually do things. - After most plugins are run,
weh
writes the files as they are described in the gigantic object to disk.
It's that simple! Static site generators aren't rocket science or whatever.
If you got confused by looking at the Jekyll source code once, that's because
Jekyll is more fully fledged than weh
is, that is, it provides some defaults.
But static site generators, at their core, are just programs that take a set of files, do something to them, and then output those files. That's it. The rest is just transformations on those files.
weh
's goal is to reduce that essence to its very base, and to give you a
bunch of building blocks with which you can make your ideal site, using only
the stuff you need!
See API.md.
Since it's really easy to write weh
plugins, anyone can make and publish one!
If you make a plugin, you should add a GitHub topic weh
and probably also
add weh
as a keyword in your package.json
.
Here's a list of all weh plugins on GitHub
To work on this repository, clone it and install the npm dependencies:
git clone https://github.com/YOURREPO
cd YOURREPO
npm install
There are a couple of npm scripts provided for convenience:
npm test
- runs linters and ava in ci modenpm run lint
- runs lintersnpm run ava
- only runs ava oncenpm run ava:ci
- runs ava in ci mode (generates coverage data)npm run ava:watch
- runs ava in watch modenpm run coverage
- generates coverage datanpm run update-coc
- pulls the latestweallbehave
code of conductnpm run deploy
- publishes npm package usingnp
This section is a little bit about how weh
compares to other static site
generators (even though it isn't really that):
- jekyll: Jekyll is a whole lot different. First off, it provides a whole lot of defaults (such as YAML Front-Matter, the Liquid language, etc) to help you build your static site extremely quickly. It's also massively geared for security, since it runs on GitHub's Pages platform. Stuff like custom plugins isn't even available there (not like that's a bad thing!).
- ghost: Ghost is just straight up a blogging platform. I don't even know why it's on AlternativeTo.
- hugo: Hugo, a bit like Jekyll, has predefined concepts like "pages" and
"tags". It's also way more stable and faster than
weh
. Why am I still writing this? - metalsmith: Metalsmith is probably the thing that's most like
weh
, and as a matter of fact, its main inspiration. It's also plugin-based, and works with roughly the same concepts. The major difference is thatweh
is more up-to-date (I like promises a lot) and that the API is fairly different. Also, it's just not really an active project with an active ecosystem anymore (sadly!).
deepmerge
- used to handle configuration managementwalk
- walks through directories to read themtrough
- handles middleware chainswrite-file-promise
andfs-readfile-promise
- promise-based versions of the standardfs
methodsdebug
- used for loggingexcluded
- handles path exclusion logicis-text-path
- provides logic to correctly read binary files
If you have any ideas as to how to eliminate a dependency, you're more than welcome to pitch it here!
- Olivia Hugger <olivia@fastmail.com>
This repository operates under the weallbehave
Code of Conduct. Its contents can be found in CODE_OF_CONDUCT.md
.
MIT (see LICENSE document)