rtgibbons / grunt-swig

Static site compiler using swig

grunt-swig

A static site compiler for grunt based on swig templates

Features being worked on: support for flat trees testing and rewrite

Call for Help

As time has passed, I haven't had a need to use this beyond the initial creation of the task. I've tried to keep up with it, but I no longer have the time to bug fix and verify the pull requests. If you are interested in helping out, get some pull requests coming in and let me know you are interested in maintaining this package.

The only thing I want to verify before I give out access is the code is somewhat clean, and the tests are are there.

Thanks!

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-swig --save-dev

One the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-swig');

The "swig" task

Overview

In your project's Gruntfile, add a section named swig to the data object passed into grunt.initConfig().

swig: {
  development: {
    init: {
        autoescape: true
    },
    dest: "www/",
    src: ['**/*.swig'],
    generateSitemap: true,
    generateRobotstxt: true,
    siteUrl: 'http://mydomain.net/',
    production: false,
    fb_appid: '1349v',
    ga_account_id: 'UA-xxxxxxxx-1',
    robots_directive: 'Disallow /',
    sitemap_priorities: {
        '_DEFAULT_': '0.5',
        'index.html': '0.8',
        'subpage.html': '0.7'
    }
  }
}

Grunt Swig will loop through files listed in src

Ex. source/index.swig. It will look for a source/index.json and add it to the rest of the variables provided in swig:development or in global.js, and then run swig against source/index.swig saving the output to www/index.html

You can also provide context, for example swig:development:blue which will perform the same actions above, but after process the JSON it will also expand the variable list with source/index.blue.json and provide the variable context to the rest of the swig template.

The siteUrl is used to build a sitemap. Right now all the other elements are hard coded, eventually this could be set in the config object.

The 'sitemap_priorities' will set custom priorities based on the page name when building the sitemap. The first item 'DEFAULT' will be the default priority used if a page name is not explicitly set. In the above example the page 'index.html' would be given priority of '0.8', 'subpage.html' would be given a priority of '0.7', and all other pages would get a priority of '0.5', You need to give the relative path to the output html file for this to work.

Path and base name of the source template file are available in tplFile variable, tplFile.path for the path and tplFile.basename for the basename.

Contributing

In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.

Release History

• 2013-12-20 - v(0.2.1) Fix Issue #20, bad logic in config variables
• 2013-11-18 - (v0.2.0) Swig 1.0 support, major refactor by @nickpack
• 2013-09-23 - Template basename and path added - Thanks @polem!
• 2013-06-08 - Fixed regression caused by init block addition preventing finding associated json payloads
• 2013-05-26 - Added init key to grunt config to allow passing over of swig options.
• 2013-05-24 - Added options to enable/disable sitemap.xml and robots.txt generation, added travis ci config.
• 2013-05-14 - Basic test suite added by Thomas Lebeau
• 2013-05-14 - respect the full source path
• 2013-04-13 - @nickpack - Refactored to work with the latest version of grunt, tidied up code and added global variable js
• 2012-11-04 - Added custom priorities to sitemap.xml when built (kengoldfarb)
• 2012-11-04 - Added ability to build robots.txt (kengoldfarb)
• 2012-11-04 - Added ability to build sitemap
• Initial Commit - compiles templates with context

ANYONE RUNNING 0.1.1 IS ADVISED TO UPGRADE TO 0.1.2 - There is an error in 0.1.1 package.json

grunt-swig's Issues

Data seperation

Can we have an option to specify a folder data/ for example to look for data .json files in it instead of having the .json files & .swig files in the same level. Or search for .json files that match the .swig file & use it something like what Assemble matching names section

for example this is much cleaner

source/
   |_ data/
       |_ index.json
       |_globals.json
       |_page.json
   |_ templates/
       |_ index.swig
       |_ about.swig
       |_ page.swig

than

source/
   |_ templates/
       |_ index.swig
       |_ index.json
       |_ about.swig
       |_ about.json
       |_ page.swig
       |_ page.json
       |_ globals.json

Options to disable sitemap and robots.txt

Hey,
Thanks for your greatly simple Grunt swig solution.
It would be amazing to allow us to disable sitemap and robots.txt generation. Right now I'm using grunt-contrib-clean for removing them after swig compiling.

Thanks in advance!

Version 1.0.0 Release and Maintenance Discussion

Version 1.0.0 Release Discussion

@rtgibbons I'm willing to help with maintenance. Here are some initial thoughts.

I propose...

Versioning Going Forward

• We begin following semantic versioning http://semver.org/
• In that spirit, the next release is version 1.0.0
• Version 1.0.0 will integrate all (good) PRs that are currently pending and other TBD features

1.0.0 Feature/Fix list

• Better test suite. Fill in gaps of missing tests.
• Add "contextRoot" option #17
• Add support for custom Swig filters #24
• Customize grunt-swig with additional tags #26
• Ability to change file extension, output directly to dest directory #28, #30, #32
• Use options in config as grunt intended #34
• Improve test suite - This needs to be far more concise
• Disable cache not working #36
• WHAT ELSE?!?

Workflow

• Create a 1.0.0 branch https://github.com/rtgibbons/grunt-swig/tree/v1.0.0
• Integrate all PRs and any new features into 1.0.0 branch
• Release a beta version RC to npm: 1.0.0-rc1
• Test/Verify
• Fix bugs, etc.
• Repeat npm beta release, incrementing 'rc' number 1.0.0-rc2 until we agree we have a stable and tested codebase
• Merge to master branch and release version 1.0.0 to npm

@rtgibbons @nickpack @zdwolfe @MrGamer - Thoughts?

Follow semantic versioning

Creating an Issue so we don't' forget.

We need to follow http://semver.org.

Basically new features that don't break the API, breaking the API (config changes) should be a major. Bug fixes are the patch (which is all we've been incrementing, incorrectly)

can not disable generateSitemap and generateRobotstxt

this code does not disable sitemap and robots generations

swig : {
            build : {
                src  : 'swig/*.swig',
                dest : 'html/',
                generateSitemap : false,
                generateRobotstxt : false
            }
        },

[email protected]

Hey,
I'd just like to remember you guys that [email protected] is about to be released. So when it gets released, grunt-swig can keep up-to-date with the amazing new features ;)

Add tests

@nickpack We should look at adding a variety of tests, it will make verify pull requests like #5 easier.

Disable Cache not working

Hi

I am not able to disable the cache in init
Is this a bug?

swig: {
    init:{
        cache: false,
        autoescape: true
    },

    dev:{
        src: ['views/**/*.swig'],
        dest: '<%= pkg.devLoc %>',
        production: false
    }
}

JSON is not loading

I have created an index.json file. This sits in the same directory as index.swig. When trying to load a property defined in index.json in index.swig, nothing happens. I have created a simple property called heading in my index.json file and am trying to load it by using:

{{ heading }}

in my swig file. Below is my swig config in Gruntfile.js and the index.json file i am loading.

swig config:

swig: {
            development: {
                init: {
                    root: "struct/swig/",
                    allowErrors: true,
                    autoescape: true
                },
                dest: "www/",
                cwd: "struct/swig/",
                src: ['**/*.swig'],
                generateSitemap: false,
                generateRobotstxt: true,   
                siteUrl: 'http://mydomain.net/',
                production: false,
                fb_appid: '1349v',
                ga_account_id: 'UA-xxxxxxxx-1',
                robots_directive: 'Disallow /',
                sitemap_priorities: {
                    '_DEFAULT_': '0.5',
                    'index': '0.8',
                    'subpage': '0.7'
                }
            }
        }

index.json

{
    "heading": "The Home Page"
}

The page renders as expected. The only thing it is missing is the JSON variable. I am not sure if I am missing a step or if there is a bug. I am fairly new to grunt and swig. Thanks for any help/direction/assistance/slap-upside-the-head that can be given.

dest option not working

No matter what is in dest, it tries to write to undefined.

Use options in config as grunt intended

Proposal that we use a more standard grunt config format of:

grunt.initConfig({
    swig: {
        options {
            generateSitemap: true
        },
        dev: {
            options{
                generateSitemap: false
            },
            src: [**/*.swig],
            dest: 'www/'
        },
        prod: {
            src: [**/*.swig],
            dest: 'www/'
        }
    }
});

Grunt newer is not working

It will be very usefull if grunt newer will work with it as i have a lot packages on which I run watch task.

include seems not working

Include tag seems not to work.
{% include './test.swig' %}

Use sub-extension for the actual extension

See #25 from @kengoldfarb

Bascially use index.html.swig to generate index.html instead of just blindly attaching .html to the file.

Possibly even search for the sub-extension to be 4 characters or less and if not then put .html, this should provide some level of backward compatibility

Enable travis hooks

@rtgibbons Now that we have some basic tests, I added a travis CI config to the repo. I've tested it on my repo, but I cannot actually enable it on this one, any chance you could have a look?

For reference: https://travis-ci.org/nickpack/grunt-swig

Add option to initialise swig

Add a section init to be passed to swig.init(). İncluding root and we can add some (all?) other options for initialising swig. (At the same time it will be more clear, as root can be mistaken to src prefix path).

So we will have something like this:

swig: {
  dist: {
    cwd: 'source',
    dest: 'www/',
    src: ['**/*.swig'],
    init: {
      root: 'source/',
      allowErrors: false,
      autoescape: true,
      cache: true,
      encoding: 'utf8',
      filters: {},
      tags: {},
      extensions: {},
      tzOffset: 0
    }
    siteUrl: 'http://localhost:9000'
  }
}

Add the support for flat trees

Delete this.

Source file "undefined" not found

I'm trying to upgrade my project to the latest, but I'm running into issues with my config giving weird outputs. It just gives me the following three lines and tells me there were no errors (which is a pretty big load of crap, since it didn't work):

>> Source file "undefined" not found.
>> Source file "undefined" not found.
>> Source file "undefined" not found.

Poking at my Gruntfile suggests the root cause is the cwd attribute. If I remove that and manually apply it to all the src files, it works. Kind of. It gives me the following, which works but is not really ideal:

Writing HTML to dist///index.html
Writing HTML to dist///faq.html
Writing HTML to dist///tools.html

I've isolated the problem down to a difference between [email protected] and [email protected] — everything else is constant

Grunt 0.4 Release

I'm posting this issue to let you know that we will be publishing Grunt 0.4 on Monday, February 18th.

If your plugin is not already Grunt 0.4 compatible, would you please consider updating it? For an overview of what's changed, please see our migration guide.

If you'd like to develop against the final version of Grunt before Monday, please specify "grunt": "0.4.0rc8" as a devDependency in your project. After Monday's release, you'll be able to use "grunt": "~0.4.0" to actually publish your plugin. If you depend on any plugins from the grunt-contrib series, please see our list of release candidates for compatible versions. All of these will be updated to final status when Grunt 0.4 is published.

Also, in an effort to reduce duplication of effort and fragmentation in the developer community, could you review the grunt-contrib series of plugins to see if any of your functionality overlaps significantly with them? Grunt-contrib is community maintained with 40+ contributors—we'd love to discuss any additions you'd like to make.

Finally, we're working on a new task format that doesn't depend on Grunt: it's called node-task. Once this is complete, there will be one more conversion, and then we'll never ask you to upgrade your plugins to support our changes again. Until that happens, thanks for bearing with us!

If you have any questions about how to proceed, please respond here, or join us in #grunt on irc.freenode.net.

Thanks, we really appreciate your work!