Replace build blocks in HTML. Like useref but done right.
npm install gulp-html-replace> Replace build blocks in HTML. Like useref but done right.
- Usage
- API
- Example
- Upgrade
shell
npm install --save-dev gulp-html-replace
`Put some blocks in your HTML file:
`html
Everything here will be replaced
`
name is the name of the block. Could consist of letters, digits, underscore ( _ ) and hyphen ( - ) symbols.API
$3
#### tasks
Type:
Object {task-name: replacement}* task-name - The name of the block in your HTML.
* replacement -
String|Array|stream.Readable|Object The replacement. See examples below.###### Simple example:
`javascript
// Options is a single string
htmlreplace({js: 'js/main.js'})// Options is an array of strings
htmlreplace({js: ['js/monster.js', 'js/hero.js']})
`
>If your options strings ends with .js or .css they will be replaced by correct script/style tags, so you don't need to specify a template like in the example below.###### Advanced example:
`javascript
// Options is an object
htmlreplace({
js: {
src: 'img/avatar.png',
tpl: '
'
}
})// Multiple tag replacement
htmlreplace({
js: {
src: [['data-main.js', 'require-src.js']],
tpl: ''
}
})
`
* src - String|Array|stream.Readable Same thing as in simple example.
* tpl - String Template string. Uses util.format() internally.> In the first example
%s will be replaced with img/avatar.png producing as the result.> In the second example
data-main="%s" and src="%s" will be replaced with data-main.js and require-src.js accordingly, producing as the result###### Extended replacements:
`javascript
// Replacement based on the file being processed
htmlreplace({
js: {
src: null,
tpl: ''
}
})
// Extended replacement combined with standard replacement
htmlreplace({
js: {
src: 'dir',
tpl: ''
}
})`
* src - null|String|Array|stream.Readable Same as examples above but null if there are no standard replacements in the template.
* tpl - String Template string. Extended replacements do not use util.format() and are performed before standard replacements.> In the first example
src is null because there are no standard replacements. %f is replaced with the name (without extension) of the file currently being processed. If the file being processed is xyzzy.html the result is .> In the second example
src has been set to the string 'dir'. Extended replacements are processed first, replacing %f with xyzzy, then %s will be replaced with dir resulting in .Valid extended replacements are:
* %f - this will be replaced with the filename, without an extension.
* %e - this will be replaced with the extension including the
. character.###### Stream replacements:
Everywhere a string replacement can be given, a stream of vinyl is also accepted. The content of each file will be treated as UTF-8 text and used for replacement. If the stream produces more than a file the behavior is the same as when an array is given.
`javascript
// Replacement is a stream
htmlreplace({
cssInline: {
src: gulp.src('style/main.scss').pipe(sass()),
tpl: ''
}
})`#### options
Type:
objectAll
false by default.- {Boolean} keepUnassigned - Whether to keep blocks with unused names or remove them.
- {Boolean} keepBlockTags - Whether to keep
and comments or remove them.
- {Boolean} resolvePaths - Try to resolve relative paths. For example if your cwd is /, your html file is /page/index.html and you set replacement as lib/file.js the result path in that html will be ../lib/file.js###### Options example:
`javascript
htmlreplace({
js: {
src: null,
tpl: ''
}
}, {
keepUnassigned: false,
keepBlockTags: false,
resolvePaths: false
})
`Example
index.html:`html
`gulpfile.js:
`javascript
var gulp = require('gulp');
var htmlreplace = require('gulp-html-replace');gulp.task('default', function() {
gulp.src('index.html')
.pipe(htmlreplace({
'css': 'styles.min.css',
'js': 'js/bundle.min.js'
}))
.pipe(gulp.dest('build/'));
});
`Result:
`html
`Upgrade
$3
>This version introduces streaming support, less confusing API, new option keepUnused and full code overhaul.
* If you used single task like this: htmlreplace('js', 'script.js') just change it to htmlreplace({js: 'script.js'})
* If you used single task with template: htmlreplace('js', 'script.js', '