swe

Sweet: Simplest Web Engine Ever, The

Sweet is a very simple static websites generator powered by Node.js and designed to run as Grunt task.

Features

• HTML, Markdown or JSON content
• Fest templates
• Multilingual content
• Typography helper (uses Richtypo.js)
• Versioned files (adds timestamp to file URL to flush browser cache)
• Plus all Grunt features: JavaScript concatenation and minification, Stylus/SASS/LESS compilation, embedded web server and much more

Installation

To use Sweet you need to install Grunt first:

$ npm install grunt-cli -g

Then install Sweet Grunt task. cd to your project’s directory and type:

$ npm install --save-dev grunt grunt-sweet

If you didn’t use Grunt before see the Getting Started to understand how it works.

Example

Go to example folder, type npm install, then grunt serve and point your browser to http://127.0.0.1:8000/. Now you can edit any file and press F5 in browser to see changes you made.

Configuration

Place Gruntfile.js to your project’s root directory.

module.exports = function(grunt) {
    grunt.initConfig({
        sweet: {
            content_dir: 'content',
            publish_dir: 'htdocs',
            templates_dir: 'templates'
        }
    });
 
    grunt.loadNpmTasks('grunt-sweet');
    grunt.registerTask('default', ['sweet']);
};

This is the mininum required config file. Type grunt to run it.

See example gruntfile in example/Gruntfile.js or my homepage’s gruntfile.

Basic Options

Required parameters are:

content_dir: 'content',
publish_dir: 'htdocs',
templates_dir: 'templates'

And optional are:

default_template_id: 'template',  // 'template' by default
uri_prefixes: '/',  // '/' by default. Use it when your site located not in root directory
url_prefixes: '/',  // '/' by default. Use it when different languages located on different domains
lang: 'en',  // 'en' by default
root_lang: 'en',  // null by default	
dot_html: false  // false by default (but always true in debug mode). Adds `.html` to all links

If your site is multilingual add this options (instead of lang):

langs: ['ru', 'en'],
url_prefixes: {
    ru: 'http://sapegin.ru/',
    en: 'http://sapegin.me/'
},
uri_prefixes: {
    'ru': '/',
    'en': '/'
}

Versioned files

files: {
    css: {
        path: 'htdocs/build/styles.css',
        href: '/build/styles.css?{version}'
    },
    js: {
        path: 'htdocs/build/scripts.js',
        href: '/build/scripts.js?{version}'
    }
}

Typographer

By default Sweet will apply Richtypo.js for $.title and $.content. To disable typographer add:

typographer: false

Using Templates

Sweet uses Fest templating engine (born at Mail.ru). See docs (in Russian) in official repo or examples here.

Content files

Content can be in HTML, Markdown of JSON. HTML files look like this:

title: Page title
template: index
var1: any value
var2: another value
 
---
 
<p>Any HTML here.</p>

Only title is required. After \n---\n you can place any HTML and then use it in your templates as $.content. Add template to specify template (or value of default_template_id will be used).

Additionally you can add any options you want. For example, var1 will be $.var1 in your templates.

Markdown files are the same as HTML but file extension should be .md or .markdown. In content part you can use GitHub flavored Markdown as well as any HTML.

JSON content is almost the same:

{
    "title": "Page title",
    "template": "index",
    "var1": "any value",
    "var2": ["You", "can", "use", "all", "JSON", "power."]
}

Template context

In addition to your own variables (see above) Sweet provides some useful template variables.

$.title

Page title.

$.pageTitle

Untypographed page title. When typographer is disabled ("typographer": false in config), $.pageTitle is equal to $.title.

$.content

Page content.

$.debug

True if debug mode is enabled (see --debug command line switch above).

$.content

Content of a page. See section Content files above.

$.lang

Language code (from langs config option).

$.path

Path of content file inside content_dir and without extension.

$.uri and $.url

URL and URI of a page: uri_prefixes/url_prefixes + $.lang + $.path.

$.map

Sitemap. Contexts of all pages (without content):

{
    "index": {
        "title": "Home page",
        "path": "index",
        "uri": "/",
        ...
    },
    "about": {
        "title": "About Us",
        "path": "about",
        "uri": "/about",
        ...
    },
    ...
}

$.files

Versioned files hash:

{
    "css": "../styles/s.css?1329399548706"
}

Template functions

You can use typographer and Markdown parser in your templates:

• $.t() — enhancing typography: non-breaking spaces, abbreviations.
• $.tt() — typography for big text: the same as rich + ampersands and hanging punctuation.
• $.tl() — simple typographer (quotes, em-dash, etc.) for user generated content (e.g. comments).
• $.md() — Markdown.
• $.mds() — Markdown (not wrapped in <p> tag).

In example: markdowned and typogrphed text from myText context variable.

<f:value>$.t($.md($.myText))</f:value>

Common data

Any “hidden” JSON file (name begins with “.”) in content_dir interprets as file with common data.

For example .common.json with this contents:

{
    "sitename": "Sweet Demo Site",
    "menu": [
        {
            "title": "Home",
            "href": "/"
        },
        {
            "title": "About",
            "href": "/about"
        }
    ]
}

will be accessible via $.common context variable.

How to Setup Development Environment

Add to your Gruntfile.js:

watch: {
    sweet: {
        files: [
            '<%= sweet.content_dir %>/**',
            '<%= sweet.templates_dir %>/**'
        ],
        tasks: 'sweet'
    }
},
connect: {
    web: {
        options: {
            port: 8000,
            base: '<config:sweet.publish_dir>'
        }
    }
}

And:

grunt.loadNpmTasks('grunt-watch');
grunt.loadNpmTasks('grunt-connect');
grunt.registerTask('serve', ['connect', 'watch']);

Then type grunt serve and point your browser to http://127.0.0.1:8000/. Now you can edit any content file or template and press F5 in browser to see changes you made.

Changelog

The changelog can be found in the Changelog.md file.

---

License

The MIT License, see the included License.md file.