grunt-include-source

> Include your sources into your HTML files automatically.

No longer maintained!

NOTE This repository is no longer actively maintained, but pull requests will still be handled.

Getting Started

This plugin requires Grunt ~0.4.4

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:

``shell
npm install --save-dev grunt-include-source
`

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

`js
grunt.loadNpmTasks('grunt-include-source');
`

The "includeSource" task

$3

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

`js
grunt.initConfig({
includeSource: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
})
`

$3

#### options.basePath
Type: String or Array[String]
Default value: ''

The base path to use when expanding files.
Can be an array to support expanding files from multiple paths.

#### options.baseUrl
Type: String
Default value: ''

The base URL to use for included files in the final result.
For example, setting baseUrl to public/ will result in files being included from public/path/to/your/file.

#### options.templates
Type: Object

The templates for sources included in html, haml, jade, pug, scss, less, ts files. Definition of single template overrides its default equivalent only.

Example:
`js
includeSource: {
options: {
basePath: 'app',
baseUrl: 'public/',
templates: {
html: {
js: '',
css: '',
},
haml: {
js: '%script{src: "{filePath}"}/',
css: '%link{href: "{filePath}", rel: "stylesheet"}/'
},
jade: { // Or pug
js: 'script(src="{filePath}", type="text/javascript")',
css: 'link(href="{filePath}", rel="stylesheet", type="text/css")'
},
scss: {
scss: '@import "{filePath}";',
css: '@import "{filePath}";',
},
less: {
less: '@import "{filePath}";',
css: '@import "{filePath}";',
},
ts: {
ts: '/// '
}
}
},
myTarget: {
files: {
'dist/index.html': 'app/index.tpl.html'
}
}
}
`

As it was mentioned above, it is possible to override only necessary templates.

#### options.typeMappings
Type: Object

Map types that are not supported but have the same syntax as an existing type. For example:
`js

includeSource: {
options: {
typeMappings: {
// CSHTML files uses the same syntax as HTML files.
'cshtml': 'html',
// LESS files use the same syntax as SCSS files.
'less': 'scss'
}
}
}
`

#### options.rename
Type: function

A way of returning a custom filepath.

See grunt.file.expandMapping.
If specified, this function will be responsible for returning the final dest filepath. By default, it joins dest and matchedSrcPath like so:
`js
rename: function(dest, matchedSrcPath, options) {
return path.join(dest, matchedSrcPath);
}
`

#### options.flatten
Type: Boolean
Default value: false

Remove the path component from all matched src files. The src file path is still joined to the specified dest.

grunt.file.expandMapping.flatten.

$3

Currently supported: html, haml, jade / pug, scss, less and ts (TypeScript).

#### HTML and CSHTML syntax


#### SCSS and LESS syntax
// include: options_go_here_as_json

#### TS syntax
///

#### include.type
The type of files that are being included.
Necessary for choosing the template for output. See options.templates for currently supported types.
Supported types are dependend on the file type you include them from.

#### include.bower
DEPRECATED: Use another Grunt plugin which is better suited for this usecase, like grunt-bower-install.
This plugin doesn't support the main property for example and is mainly used for development purposes to directly include external sources.

Include files of the specified Bower component. The component should have a bower.json meta data with a property called sources.
This property should contain the files grouped by type, which are passed through the grunt.file.expand method.

Example:
`js
{
"name": "package.name",
...
"sources": {
"js": [
"src/scripts/*/.js",
"lib/compiled-templates.js"
],
"css": "src/styles/*/.css"
}
}
`

#### include.files
Include the given files. Files are passed through the grunt.file.expandMapping method (see include.rename and include.flatten options).

#### include.basePath
Set to override the basePath set in the options.

#### include.baseUrl
Set to override the baseUrl set in the options.

#### include.ordering
Type: String
Default value: undefined

Ordering method to be used when including files. Currently supported methods are:
* undefined (default) - included files are sorted by their paths alphabetically in ascending order.
* 'top-down' - files from the parent directory will be included before files from subdirectories.

#### Overwriting files

To set the source file as the destination file use an /include comment:

`html




`

When includeSource is run it will keep the include comments and only update the includes inside it.

This works the same way for Less/Sass, by using // /include.

$3

Configure your task like this:

`js
grunt.initConfig({
includeSource: {
options: {
basePath: 'app',
baseUrl: 'public/'
},
myTarget: {
files: {
'dist/index.html': 'app/index.tpl.html'
}
}
}
})
`

The file index.tpl.html could contain, for example:
`html




















`
And the resulting file index.html will look something like:
`html























``

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

See CHANGELOG.md.