https://github.com/hanamura/gulp-minisite
Static site generator for Gulp ecosystem.
https://github.com/hanamura/gulp-minisite
blog cms gulp gulp-plugin static-site-generator
Last synced: 8 days ago
JSON representation
Static site generator for Gulp ecosystem.
- Host: GitHub
- URL: https://github.com/hanamura/gulp-minisite
- Owner: hanamura
- License: mit
- Created: 2015-05-26T10:51:39.000Z (almost 11 years ago)
- Default Branch: master
- Last Pushed: 2017-10-25T06:11:02.000Z (over 8 years ago)
- Last Synced: 2025-11-13T23:22:43.846Z (4 months ago)
- Topics: blog, cms, gulp, gulp-plugin, static-site-generator
- Language: JavaScript
- Homepage:
- Size: 144 KB
- Stars: 12
- Watchers: 2
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gulp-minisite [](https://travis-ci.org/hanamura/gulp-minisite)
Static site generator for Gulp ecosystem.
## Why?
1. A single build system is enough for static site development. I already have [Gulp](http://gulpjs.com). I don’t want to work hard for making full-featured-standalone-static-site-generator to work well with Gulp/Npm/Node. Or to compile, minify, and optimize many different kinds of files properly in their way, while Gulp does everything well.
Making user-friendly presentation (HTML and pertty permalinks) from developer-friendly expression (eg. JSON, YAML, or Markdown and pretty filenames) is the one thing to do well for gulp-minisite.
2. To start small and expand flexibly, gulp-minisite keeps it simple, works without complex configutations, and provides some handy options and features.
### gulp-minisite does:
- transform source files into HTML using template engine.
- compose useful data and you can use it in a template file.
- build clean permalink structure.
### gulp-minisite does NOT:
- compile any file into CSS or JavaScript. Do it with Gulp and your favorite compiler.
- minify or optimize any kind of files. Do it with Gulp and your favorite minifier or optimizer.
- watch file changes. Do it with `gulp.watch()`.
- run a local webserver. Do it with [gulp-webserver](https://github.com/schickling/gulp-webserver).
- force you to use specific template engine. ([Nunjucks](https://mozilla.github.io/nunjucks/) by default, but you can change it)
- provide flexible permalink configurations [like](http://jekyllrb.com/docs/permalinks/) [that](https://gohugo.io/extras/permalinks/). Just put files and follow the convensions.
- generate dynamic pages like paginated indexes. Traverse files and generate “dynamic“ pages manually before executing gulp-minisite tasks. (But considering some sort of helpers)
- behave like a blog engine. It’s made for a general website (including a blog).
- have any theme.
## Install
```sh
$ npm install gulp-minisite --save-dev
```
## Tutorial
### Start with minimum example
Directory structure:
```
.
├── src
| └── index.html
├── gulpfile.js
└── package.json
```
`src/index.html`:
```html
Hello
Hello World
```
`gulpfile.js`:
```javascript
var gulp = require('gulp');
var minisite = require('gulp-minisite');
gulp.task('minisite', function() {
return gulp.src('src/**/*')
.pipe(minisite())
.pipe(gulp.dest('dest'));
});
```
#### Output
```
...
├── dest
| └── index.html
...
```
`dest/index.html`:
```html
Hello
Hello World
```
Just copied `index.html`. This is still useless.
### Use YAML and template
Add template:
```
.
├── src
| └── index.html
├── template <- added
| └── home.html <- added
...
```
`template/home.html`:
```jinja
{{ page.title }}
{{ page.description }}
```
By default, you can use [Nunjucks]() template engine. See [the document](https://mozilla.github.io/nunjucks/templating.html) for further information.
Rename `src/index.html` to `src/index.yml` and modify content:
```
.
├── src
| └── index.yml <- rename and modify
...
```
`src/index.yml`:
```yaml
template: home.html
title: Hello
description: Hello World
```
Specify template name by `template` attribute.
#### Output
`dest/index.html`:
```html
Hello
Hello World
```
### Use Markdown with YAML [front-matter](http://jekyllrb.com/docs/frontmatter/)
```
.
├── src
| └── index.md <- renamed
...
```
`src/index.md`:
```markdown
---
template: home.html
title: Hello
---
Hello World with **Markdown** syntax.
```
Update `template/home.html`:
```jinja
{{ page.title }}
{{ page.body | markdown }}
```
#### Output
`dest/index.html`:
```html
Hello
Hello World with Markdown syntax.
```
### Add about page
Add document and template:
```
.
├── src
| ├── index.md
| └── about.yml <- added
├── template
| ├── home.html
| └── about.html <- added
...
```
`src/about.yml`:
```yaml
template: about.html
title: About
description: [Contact me](mailto:mail@example.com)
```
`template/about.html`:
```jinja
{{ page.title }}
{{ page.description | markdown }}
```
#### Output
```
...
├── dest
| ├── index.html
| └── about
| └── index.html
...
```
`dest/about/index.html`:
```html
About
```
### Add product pages
Add some files:
```
.
├── src
| ├── index.md
| ├── about.yml
| └── product <- added
| ├── index.yml <- added
| ├── salt.yml <- added
| ├── pepper.yml <- added
| └── sugar.yml <- added
├── template
| ├── home.html
| ├── about.html
| ├── product-index.html <- added
| ├── product-detail.html <- added
...
```
`src/product/index.yml`:
```yaml
template: product-index.html
title: Products
```
`src/product/salt.yml`:
```yaml
template: product-detail.html
title: Salt
description: This is salty.
```
`template/product-index.html`:
```jinja
{% for product in page.collection %}
{% endfor %}
```
`template/product-detail.html`
```jinja
{{ page.title }}
{{ page.description }}
```
#### Output
```
...
├── dest
| ├── index.html
| ├── about
| | └── index.html
| └── product
| ├── index.html
| ├── salt
| | └── index.html
| ├── pepper
| | └── index.html
| └── sugar
| └── index.html
...
```
`dest/product/index.html`:
```html
```
`dest/product/salt/index.html`:
```html
Salt
This is salty.
```
Products are sorted by filename.
### Sort products by specific order
Rename product files:
```
...
| └── product
| ├── index.yml
| ├── #01.salt.yml <- renamed
| ├── #02.pepper.yml <- renamed
| └── #03.sugar.yml <- renamed
...
```
#### Output
`dest/product/index.html`:
```html
```
Order part of filename is stripped from output.
### Add site name for all pages
Add `site` option in `gulpfile.js`:
```javascript
...
gulp.task('minisite', function() {
return gulp.src('src/**/*')
.pipe(minisite({
site: {name: 'Hello Website'}
}))
.pipe(gulp.dest('dest'));
});
```
Prepend title tag to all template files:
```jinja
{% if page.path === '/' %}
{{ site.name }}
{% else %}
{{ page.title }} - {{ site.name }}
{% endif %}
...
```
#### Output
`dest/index.html`:
```html
Hello Website
...
```
`dest/about/index.html`:
```html
About - Hello Website
...
```
### Add Japanese language version of files
Suffix language name:
```
.
├── src
| ├── index.md
| ├── index.ja.md <- added
| ├── about.html
| ├── about.ja.html <- added
| └── product
| ├── index.yml
| ├── index.ja.yml <- added
| ├── #01.salt.yml
| ├── #01.salt.ja.yml <- added
| ├── #02.pepper.yml
| ├── #02.pepper.ja.yml <- added
| ├── #03.sugar.yml
| └── #03.sugar.ja.yml <- added
...
```
`src/index.ja.md`:
```markdown
---
template: home.html
title: こんにちは
---
こんにちは、世界
```
Specify `locales` and `defaultLocale` in `gulpfile.js`:
```javascript
...
gulp.task('minisite', function() {
return gulp.src('src/**/*')
.pipe(minisite({
site: {name: 'Hello Website'},
locales: ['en', 'ja'],
defaultLocale: 'en',
}))
.pipe(gulp.dest('dest'));
});
```
#### Output
```
...
├── dest
| ├── index.html
| ├── about
| | └── index.html
| ├── product
| | ├── index.html
| | ├── salt
| | | └── index.html
| | ├── pepper
| | | └── index.html
| | └── sugar
| | └── index.html
| └── ja
| ├── index.html
| ├── about
| | └── index.html
| └── product
| ├── index.html
| ├── salt
| | └── index.html
| ├── pepper
| | └── index.html
| └── sugar
| └── index.html
...
```
`dest/index.html`:
```html
...
こんにちは
こんにちは、世界
```
### Write draft document
Start filename with `_`:
```
.
├── src
| ├── _contact.html <- added
...
```
`gulpfile.js`:
```javascript
...
var gutil = require('gulp-util');
...
gulp.task('minisite', function() {
return gulp.src('src/**/*')
.pipe(minisite({
site: {name: 'Hello Website'},
locales: ['en', 'ja'],
defaultLocale: 'en',
draft: !gutil.env.production,
}))
.pipe(gulp.dest('dest'));
});
```
#### Output
With `$ gulp minisite`:
```
...
├── dest
| ├── contact
| | └── index.html
...
```
But with `$ gulp minisite --production`, `dest/contact/index.html` won’t be generated.
### Add image files
```
...
├── src
| ├── img <- added
| | ├── logo.png <- added
| | ├── logo.ja.png <- added
| | ├── logo@2x.png <- added
| | └── logo@2x.ja.png <- added
...
```
#### Output
```
...
├── dest
| ├── img
| | ├── logo.png
| | └── logo@2x.png
...
| └── ja
| ├── img
| | ├── logo.png
| | └── logo@2x.png
...
```
If your files aren’t document, gulp-minisite just relocate and copies them.
### Use Sass, CoffeeScript, etc.
gulp-minisite does nothing for that. Just proceed them as you like.
```
...
├── style
| └── main.scss
├── script
| └── main.coffee
...
```
`gulpfile.js`:
```javascript
...
var sass = require('gulp-sass');
var coffee = require('gulp-coffee');
...
gulp.task('css', function() {
return gulp.src('style/**/*')
.pipe(sass())
.pipe(gulp.dest('dest/css'));
});
gulp.task('js', function() {
return gulp.src('script/**/*')
.pipe(coffee())
.pipe(gulp.dest('dest/js'));
});
...
```
## Options
### minisite([options])
#### options.locales
- Type: `Array` of `String`
- Default: `null`
Acceptable locale names.
#### options.defaultLocale
- Type: `String`
- Default: `null`
If `defaultLocale` specified, any file without locale part in filename will be assigned that locale.
#### options.site
- Type: `Object`
- Default: `null`
Site-global variable. You can refer the object in template files like `{{ site.name }}`.
#### options.templateEngine
- Type: `Function`
- Default: Nunjucks template engine
Template engine’s render function. The function should receive template name (actually, `template` value of document) and data, and return rendered string.
To use [jade](https://github.com/jadejs/jade):
```javascript
...
templateEngine: function(tmplName, tmplData) {
var jade = require('jade');
var path = require('path');
var tmplDir = 'jade';
return jade.renderFile(path.join(tmplDir, tmplName), tmplData);
},
...
```
#### options.draft
- Type: `Boolean`
- Default: `false`
If `true`, draft files (their filename starts with `_`) will be proceeded.
#### options.dataExtensions
- Type: `Array` of `String`
- Default: `['yml', 'yaml', 'json']`
File extensions that are treated as documents. If you want YAML/JSON files not to turn out to be HTML, pass `[]` or `null`.
## License
MIT