ZUME
An opinionated static-site generator with gulp.
Directory structure:
root/
|_ gulpfile.js
|_ package.json
|_ src/
|_ css
|_ js
|_ img
|_ data
|_ templates
|_ build/
Quick start:
Only for simple cases without configuration you can use the CLI to start and run a new project:
npm i zume -gmkdir my-projectcd my-projectzume initzume server
Using with gulp
Example of the gulpfile.js
:
const zume = ;const gulp = zume; gulp; gulp; gulp;gulp;gulp; gulp;gulp;
API
First, you have to create a zume
instance passing the config data. Use the static function create()
for this purpose:
const zume =
The full list of available settings:
Name | Default | Description |
---|---|---|
dev |
true |
If it's in dev environment or not |
url |
"http://localhost" |
The full url of the site |
cwd |
process.cwd() |
The working directory |
src |
"src" |
The directory with the source files |
dest |
"build" |
The directory in which generate the static site |
server |
[object] |
The browser-sync server options |
The zume
instance provides the following functions:
Name | Description |
---|---|
zume.gulp() |
Returns the gulp instance used by zume. |
zume.path() |
Returns any path of the project. For example: zume.path('foo') returns "/path/to/project/foo" . |
zume.src() |
Returns any path of the src folder. For example: zume.src('foo') returns "/path/to/project/src/foo" . |
zume.dest() |
Returns any path of the build folder. For example: zume.src('img') returns "/path/to/project/build/img" . |
zume.url() |
Returns a public url path. For example: zume.url('foo') returns "/foo" . |
zume.fullUrl() |
Returns a public full url path. For example: zume.fullUrl('foo') returns "http://example.com/foo" . |
zume.serve() |
Init a new http server using browsersync. |
zume.clear() |
Removes de build folder. |
Task
Zume contains the tasks html
, css
, js
, img
and files
. To create a task, just need to do the following:
const html = zume;
Available options:
Name | Description |
---|---|
task |
The gulp task name used to relaunch by the watcher. The default value in html is html , css is css , and so on. |
src |
Absolute directory where are the src files (by default is zume.src() ) |
base |
Relative directory to src and dest used to search for files and output the result. |
pattern |
The pattern used to search files. The default value in html is data/**/*.md , in css is *.css , etc. |
watchPattern |
Additional patterns added to the watcher. |
There are some functions available in all tasks:
.pipe(plugin)
Allow to pipe more gulp plugins to the stream.each(callback)
To execute a callback for each file.filter(callback)
To filter some files.fork(callback)
To filter some files and create a different fork with them.add(options)
To create a new stream task ready to merge it in the main stream..dest()
To save the files in the build folder and return a promise.
Example:
zume // Get the markdown files // Extract the frontmatter // Render the markdown // Parse the yaml // Merge yaml and markdown files // Change the file names // Execute a function with these files // Merge these files again with the main stream // Apply the templates // Save to build folder
HTML Generation
To generate html pages, you need to create a html task and use some of its functions:
zume
frontMatter
Handle the front matter of .md
files using front-matter. In addition to the front matter, you can pass an object with common data to all files. Example:
html
yaml
Handle the content of .yaml
files. Useful if you don't need md files, just yaml content. You can pass an object with common data to all files. Example:
html
markdown
Parse the content of the files as markdown using markdown-it. You can pass a function to configure the MarkdownIt instance:
html
In addition to that, it also creates two variables: markdown
and markdownInline
that can be used in the templates to render markdown.
permalink
Renames the *.md
files to */index.html
in order to generate pretty urls. For example: the file about.md
is renamed to about/index.html
.
html
navigation
Creates a tree structure with all files to build a navigation menu. Example:
html
<? nav.forEach(section => { ?> <?= section.title ?> <? }) ?>
Use the variable position
to change the order of the elements.
You can override the default values of the sections:
html;
ejs
Build the html files using ejs. In addition to the front matter values, the templates have two more variables: content
to return the file content and zume
containing the instance of zume, that you can use to generate, for example, new urls. You can configure the options in the first argument. Example with the default options:
html
<?= title ?> <?- content ?> About us
urls
Search and fix all relative urls in the html (a
, img
, link
, script
, source
, etc...), to use the site url as base. Optionally, can makes all urls relative each other, allowing to execute the web directly from the file system (file:
protocol). The configuration value index
insert automatically a index.html
at the end of the urls.
html
inline
To inline the tags containing the inline="true"
attribute. Supports <script>
, <link>
and <img>
html
cheerio
Run cheerio in all html pages. Useful to make changes in the html using the jQuery sintax.
html; //object with optionshtml
JS
Task used to generate js content.
zume ;
webpack
Runs webpack to generate the javascript files. Example with the default configuration:
js
CSS
Task used to generate css content.
zume ;
postcss
Runs postcss to generate the css files, with the following plugins:
- postcss-import
- postcss-url
- cssnext
- cssnano (enabled only in production mode)
Img
Simple task used to handle img files:
zume;
Files
Simple task used just to copy files:
zume;