Replace build blocks in HTML. Like useref but done right.
Replace build blocks in HTML. Like useref but done right.
Install:
npm install --save-dev gulp-html-replace
Put some blocks in your HTML file:
<!-- build:<name> -->
Everything here will be replaced
<!-- endbuild -->
name
is the name of the block. Could consist of letters, digits, underscore ( _ ) and hyphen ( - ) symbols.
Type: Object
{task-name: replacement}
String|Array|stream.Readable|Object
The replacement. See examples below.// 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.
// Options is an object
htmlreplace({
js: {
src: 'img/avatar.png',
tpl: '<img src="%s" align="left" />'
}
})
// Multiple tag replacement
htmlreplace({
js: {
src: [['data-main.js', 'require-src.js']],
tpl: '<script data-main="%s" src="%s"></script>'
}
})
String|Array|stream.Readable
Same thing as in simple example.String
Template string. Uses util.format() internally.In the first example
%s
will be replaced withimg/avatar.png
producing<img src="img/avatar.png" align="left">
as the result.
In the second example
data-main="%s"
andsrc="%s"
will be replaced withdata-main.js
andrequire-src.js
accordingly, producing<script data-main="data-main.js" src="require-src.js"></script>
as the result
// Replacement based on the file being processed
htmlreplace({
js: {
src: null,
tpl: '<script src="%f".js></script>'
}
})
// Extended replacement combined with standard replacement
htmlreplace({
js: {
src: 'dir',
tpl: '<script src="%s/%f".js"></script>'
}
})
null|String|Array|stream.Readable
Same as examples above but null if there are no standard replacements in the template.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 isxyzzy.html
the result is<script src="xyzzy.js"></script>
.
In the second example
src
has been set to the string'dir'
. Extended replacements are processed first, replacing%f
withxyzzy
, then%s
will be replaced withdir
resulting in<script src="dir/xyzzy.js"></script>
.
Valid extended replacements are:
.
character.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.
// Replacement is a stream
htmlreplace({
cssInline: {
src: gulp.src('style/main.scss').pipe(sass()),
tpl: '<style>%s</style>'
}
})
Type: object
All false
by default.
<!-- build -->
and <!-- endbuild -->
comments or remove them.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
htmlreplace({
js: {
src: null,
tpl: '<script src="%f".js></script>'
}
}, {
keepUnassigned: false,
keepBlockTags: false,
resolvePaths: false
})
index.html:
<!DOCTYPE html>
<html>
<head>
<!-- build:css -->
<link rel="stylesheet" href="css/normalize.css">
<link rel="stylesheet" href="css/main.css">
<!-- endbuild -->
</head>
<body>
<!-- build:js -->
<script src="js/player.js"></script>
<script src="js/monster.js"></script>
<script src="js/world.js"></script>
<!-- endbuild -->
gulpfile.js:
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:
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="styles.min.css">
</head>
<body>
<script src="js/bundle.min.js"></script>
This version introduces streaming support, less confusing API, new option keepUnused and full code overhaul.
htmlreplace('js', 'script.js')
just change it to htmlreplace({js: 'script.js'})
htmlreplace('js', 'script.js', '<script="%s">')
change it to htmlreplace({js: {src: 'script.js', tpl: '<script="%s">'})
files
renamed to src
, see previous example. Rename if needed.This version switches to the new way of specifying options which is more future-proof. Before it was
htmlreplace(tasks, keepUnassigned = false)
, now it'shtmlreplace(tasks, {keepUnassigned: false})
. No action required, old syntax will still work, but it is advisable to switch to the new syntax.