{"id":15062074,"url":"https://github.com/bmatcuk/html-brunch-static","last_synced_at":"2025-04-10T09:54:37.779Z","repository":{"id":52165241,"uuid":"42076153","full_name":"bmatcuk/html-brunch-static","owner":"bmatcuk","description":"Transform static html files in brunch.","archived":false,"fork":false,"pushed_at":"2022-12-10T16:09:40.000Z","size":317,"stargazers_count":24,"open_issues_count":6,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-20T14:41:49.634Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bmatcuk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-07T21:51:21.000Z","updated_at":"2020-12-26T16:53:23.000Z","dependencies_parsed_at":"2023-01-26T03:45:28.531Z","dependency_job_id":null,"html_url":"https://github.com/bmatcuk/html-brunch-static","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fhtml-brunch-static","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fhtml-brunch-static/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fhtml-brunch-static/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bmatcuk%2Fhtml-brunch-static/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bmatcuk","download_url":"https://codeload.github.com/bmatcuk/html-brunch-static/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248198841,"owners_count":21063626,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T23:29:58.037Z","updated_at":"2025-04-10T09:54:37.756Z","avatar_url":"https://github.com/bmatcuk.png","language":"JavaScript","funding_links":[],"categories":["Brunch plugins"],"sub_categories":["Others"],"readme":"![Release](https://img.shields.io/npm/v/html-brunch-static.svg)\n\n# html-brunch-static\nTransform static html files in brunch.\n\nhtml-brunch-static is a processor for [brunch-static](https://github.com/bmatcuk/brunch-static), a [brunch](http://brunch.io/) plugin designed to handle static files. html-brunch-static can convert a variety of template languages into static html files with support for layouts and partial views.\n\nIf you want to dive into writing your own processor, [jump down](#writing-html-brunch-static-processors). Otherwise, keep reading.\n\n## Installation\nhtml-brunch-static depends on [brunch-static](https://github.com/bmatcuk/brunch-static), so, you will need to install both plugins. The recommended method is via npm:\n\n```bash\nnpm install --save-dev brunch-static html-brunch-static\n```\n\nOr manually:\n\n* Add `\"brunch-static\": \"x.y.z\"` to package.json\n* Add `\"html-brunch-static\": \"x.y.z\"` to package.json\n* Run `npm install`\n* Alternatively, you may use the latest git version with:\n  * `\"brunch-static\": \"git+ssh://git@github.com:bmatcuk/brunch-static\"`\n  * `\"html-brunch-static\": \"git+ssh://git@github.com:bmatcuk/html-brunch-static\"`\n\n## Configuration\nAdd html-brunch-static to your list of brunch-static processors:\n\n```coffee\nexports.config =\n  ...\n  plugins:\n    static:\n      processors: [\n        require('html-brunch-static') {\n          processors: [ ... ]\n          defaultContext: { ... }\n          partials: ...\n          layouts: ...\n          handlebars: {\n            enableProcessor: ...\n            helpers: { ... }\n            ...\n          }\n          minify: ...\n        }\n      ]\n```\n\n* **processors** _(default: `[]`)_\n  \u003e _processors_ is an array of html processors. See [available processors](#available-processors) below for a list.\n\n* **defaultContext** _(default: `{}`)_\n  \u003e To set default values for the _context_ of your files, use _defaultContext_. See \"[Context, Layouts, and Partials](#context-layouts-and-partials)\" below for more details on the context.\n\n* **partials** _(default: `/partials?/`)_\n  \u003e _partials_ is an [anymatch](https://github.com/es128/anymatch) that will be used to determine what files are [partials](#partials). This means it can be either a string with globs, a regex, or a function that takes a single parameter (a filename) and returns true if it is a partial view and false otherwise. The default setting will match any filename that includes the word \"partial\" (or \"partials\") anywhere in the path, for example: `app/partials/whatever.ext`.\n\n* **layouts** _(default: `/layouts?/`)_\n  \u003e Like _partials_ above, _layouts_ is an [anymatch](https://github.com/es128/anymatch) that will be used to determine what files are [layouts](#layouts). It may also be a string with globs, a regex, or a function that takes a filename and returns true/false. The default setting will match any filename that includes the word \"layout\" (or \"layouts\") anywhere in the path, for example: `app/layouts/whatever.ext`.\n\n* **handlebars** _(default: `null`)_\n  \u003e Default options for handlebars (see [handlebars.js documentation](http://handlebarsjs.com/reference.html)). These options, with the exception of _enableProcessor_ and _helpers_ (see below), are passed verbatim to handlebars and can be overridden in the front matter ([see below](#context-layouts-and-partials)).\n  \u003e\n  \u003e * **enableProcessor** _(default: `false`)_\n  \u003e\n  \u003e   \u003e _enableProcessor_ may either be true or an object containing objects to pass to the handlebars processor. Either way will enable the built-in support for handlebar files. See below for the options available.\n  \u003e\n  \u003e * **helpers** _(default: `null`)_\n  \u003e   \u003e _helpers_ can be used to specify custom handlebars helpers. This option should be a hash where the keys are the names of the helpers and the values are functions. This hash is passed, verbatim, to `Handlebars.registerHelper()` (see [handlebars.js documentation](http://handlebarsjs.com/reference.html)).\n\n* **minify** _(default: `false`)_\n  \u003e Minify the resulting html using [html-minifier](https://github.com/kangax/html-minifier). To enable, set this value to `true` to use the default options, or set to a hash of options that will be passed directly to html-minifier. See html-minifier's documentation for a list of valid options and their defaults.\n\nThe following options are available if you enable the built-in handlebars processor:\n\n```coffee\nenableProcessor:\n  fileMatch: ...\n  fileTransform: ((filename) -\u003e ...)\n```\n\n* **fileMatch** _(default: `/\\.static\\.(hbs|handlebars)$/`)_\n  \u003e _fileMatch_ is an [anymatch](https://github.com/es128/anymatch) that is used to determine which files will be handled by the handlebars processor. As an anymatch, it may be a string with globs, a regex, or a function that takes a filename and returns true or false. The default will match files that end with `.static.hbs` or `.static.handlebars`.\n\n* **fileTransform** _(default: `(f) -\u003e f.replace(/\\.static\\.\\w+$/, '.html')`)_\n  \u003e _fileTransform_ converts the input filename into an html filename. It takes a filename as input and returns the new filename with the html extension. If you set the _fileMatch_ property above, you'll probably need to set this option as well to ensure that your output files end with the html extension.\n\n### Note\nThe value of _partials_ and _layouts_ may be the same if you want to put them all together. In a lot of similar static site generators, partials and layouts might start with an underscore, such as `_layout.html`. You can do this (and set _partials_ and _layouts_ to something like `\"**/_*\"`), but be aware that, by default, brunch will ignore any files that start with an underscore. What this means is that any changes to these files will not trigger brunch to recompile any files that are dependent on those partials and layouts. This problem can be fixed if you change brunch's `conventions.ignored` setting to not ignore files that begin with an underscore.\n\n## Available Processors\nBelow are the currently available processors for html-brunch-static. If you'd like for your processor to be included in this list, [create an issue](https://github.com/bmatcuk/brunch-static/issues/new) with your project's URL and a description.\n\n* Markdown: [marked-brunch-static](https://github.com/bmatcuk/marked-brunch-static)\n* Nunjucks: [njk-brunch-static](https://github.com/bmatcuk/njk-brunch-static)\n* Pug: [pug-brunch-static](https://github.com/bmatcuk/pug-brunch-static)\n* Jade: [jade-brunch-static](https://github.com/bmatcuk/jade-brunch-static)\n* Handlebars: built-in (see the [handlebars.enableProcessor option](#configuration) above)\n\n## Context, Layouts, and Partials\nhtml-brunch-static has full support for using layouts and partials in your templates. In fact, you can have multiple levels of layouts if you'd like. These features are orchestrated by including [YAML](http://yaml.org/) or JSON _front matter_ at the top of your template files. Front matter sets the _context_ of the file, which is bubbled up (and possibily overridden) by the layout, and the layout's layout, etc.\n\n### Example\nBy default, processors will look for files ending in the extension `.static.ext` (ex: `.static.jade`). This way, html-brunch-static does not interfere with other brunch plugins which are meant to handle dynamic files. This behavior can be changed using the `fileMatch` and `fileTransform` options for the respective processor (see documentation for [marked-brunch-static](https://github.com/bmatcuk/marked-brunch-static), [jade-brunch-static](https://github.com/bmatcuk/jade-brunch-static), etc).\n\nArmed with that knowledge, let's say I have the following file `app/index.static.md`:\n\n```markdown\n---\ntitle: html-brunch-static's awesome test page\n_options:\n  layout: app/layouts/main.static.jade\n  partials:\n    - app/partials/greetings.static.hbs\n---\n{{\u003egreetings}}\n\nThis is **html-brunch-static's** super awesome test page.\n```\n\nEverything between the `---`'s is the front matter. Here, I've chosen to write my front matter in [YAML](http://yaml.org/), but I could have also written it in JSON. This whole block is referred to as the _context_ of this file.\n\nIn this example, We can see that this file wants to use a layout (`app/layouts/main.static.jade`) and includes one partial view (`app/partials/greetings.static.hbs`). All partial views that your file uses must be declared in the front matter so that html-brunch-static knows to load them. This also illustrates another powerful feature of html-brunch-static: layouts and partials can be written in any templating language that html-brunch-static has a processor for, and they don't need to match. This file is written in markdown, the layout in jade, and the partial is handlebars file. Neat!\n\nWhat's that `{{\u003egreetings}}` thing all about? Well, after html-brunch-static converts your file to html, it runs the file through [handlebars](http://handlebarsjs.com/) to allow your files to use the context to do some cool things. Here, `{{\u003e...}}` is the handlebars way of saying \"use the partial called greetings\". Since we declared that we're using the `app/partials/greetings.static.hbs` partial in our front matter, it will be loaded and inserted into your file here.\n\nNote that your partial files must match the `fileMatch` rule for the processor that will handle the file. This means, by default, you'll need to name the file with `.static.ext`. html-brunch-static gives you multiple ways to reference your partial based on the filename though: for example, `app/partials/greetings.static.hbs` can be referenced as `{{\u003egreetings.static.hbs}}`, `{{\u003egreetings.static}}`, or `{{\u003egreetings}}`.\n\nOk, so what does our partial look like? I give you `app/partials/greetings.static.hbs`:\n\n```html\n\u003ch1\u003eWelcome to {{title}}\u003c/h1\u003e\n```\n\nPretty simple. This file has no front matter of its own, but since it's being included in our index.static.md, it inherits the _context_ of index.static.md. This means that our `title` is available to it. Neat!\n\nFinally, our layout, `app/layouts/main.static.jade`:\n\n```jade\ndoctype html\nhtml\n  head\n    title {{title}}\n  body\n    | {{content}}\n```\n\nThe _context_ of our page bubbles up to our layout, so our title is still available. If our layout included some front matter of its own, it could override the title. The content of our page is available to the layout with the `{{content}}`. That \"pipe\" (`|`) in front of `{{content}}` is just [jade](http://jade-lang.com/)'s way of saying that everything after it should just be included on the page verbatim.\n\nNote that, like partials, layout files must match the `fileMatch` rule for the processor that will handle the file. This means, by default, you'll need to name the file with `.static.ext`.\n\nAlright, let's take a quick look at our `package.json`:\n\n```javascript\n{\n  ...\n  \"devDependencies\": {\n    \"brunch\": \"x.y.z\",\n    \"brunch-static\": \"x.y.z\",\n    \"html-brunch-static\": \"x.y.z\",\n    \"marked-brunch-static\": \"x.y.z\",\n    \"jade-brunch-static\": \"x.y.z\",\n    ...\n  },\n  ...\n}\n```\n\n... and our `brunch-config.coffee`:\n\n```coffee\nexports.config =\n  ...\n  plugins:\n    static:\n      processors: [\n        require('html-brunch-static') {\n          handlebars:\n            enableProcessor: true\n          processors: [\n            require('marked-brunch-static')()\n            require('jade-brunch-static')(pretty: true)\n          ]\n        }\n      ]\n```\n\nNothing special in either of those files other than including brunch-static, html-brunch-static, and the markdown and jade processors. We're using the `pretty` option with jade because... pretty is pretty.\n\nNow if we run `brunch build`, we should get our output `public/index.html`:\n\n```html\n\u003c!doctype html\u003e\n\u003chtml\u003e\n  \u003chead\u003e\n    \u003ctitle\u003ehtml-brunch-static's awesome test page\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003cp\u003e\u003ch1\u003eWelcome to html-brunch-static's awesome test page.\u003c/h1\u003e\u003c/p\u003e\n    \u003cp\u003eThis is \u003cb\u003ehtml-brunch-static's\u003c/b\u003e super awesome test page.\u003c/p\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Front Matter Options\nAs touched on above, the front matter can contain some options. The following options are available. Note that some processors may define some additional options.\n\n```yaml\n---\n_options:\n  layout: ...\n  partials:\n    ...\n  handlebars:\n    ...\n---\n```\n\n* **layout**\n  \u003e _layout_ is the layout file you want to use for this file. See above.\n\n* **partials**\n  \u003e _partials_ is a list of partials that you want to use in this file. They must be declared here so that html-brunch-static knows to load them. See above.\n\n* **handlebars**\n  \u003e _handlebars_ overrides the [handlebars](#configuration) option in the `brunch-config.coffee` file. These options are passed verbatim to handlebars (see the [handlebars.js documentation](http://handlebarsjs.com/reference.html)).\n\n## Writing html-brunch-static Processors\nProcessors are kind of similar to Brunch plugins themselves: an object that has certain members and methods. It's recommended that your project follows the following naming scheme: `whatever-brunch-static` to make it easy to find in npm.\n\n```javascript\nvar MyHtmlProcessor = function(config) { ... };\n\nMyHtmlProcessor.prototype = {\n  handles: ...,\n  transformPath: function(filename) { ... },\n  acceptsContext: true/false,\n  compile: function(data, filename, options, callback) { ... }\n};\n\n// export a simple function to make it easier to include in brunch-config.coffee\nmodule.exports = function(config) { return new MyHtmlProcessor(config); };\n```\n\n* **handles**\n  \u003e _handles_ is an [anymatch](https://github.com/es128/anymatch) that will be used to determine if your processor can handle a given file. This means it can be either be a string (using globs), a regex, or a function that takes a single parameter (the filename) and returns true if your processor can handle it, or false otherwise.\n\n* **transformPath**\n  \u003e _transformPath_ is a function that will receive the original filename and return the filename for the output. In most cases, this just involves replacing the file extension with html. For example, the input filename might be something like `app/path/to/file.static.jade`. This function would return `app/path/to/file.html`.\n\n* **compile**\n  \u003e _compile_ receives the contents of the file, the file's name, options, and a callback function. The options come straight from the file's front matter (see [Front Matter Options](#front-matter-options)), so, be aware that they might be null (if the user didn't set any options), or the values you're looking for might not have been set at all! After you have finished processing the file's data, you will need to call the callback function with the following:\n  \u003e\n  \u003e * `callback(err, data, dependencies)`\n  \u003e   * **err** informs html-brunch-static when something goes wrong. If there were no issues, pass null.\n  \u003e   * **data** is the html output of your processor.\n  \u003e   * **dependencies** is an array of dependencies that your processor has found for the file. If the file has dependencies on layouts and partial views, html-brunch-static already tracks those, but the language you are implementing in your processor might have some way of its own to include the content of other files. If this is the case, you should return those dependencies here so html-brunch-static can track them, too. Otherwise, you can just pass null.\n\n* **acceptsContext**\n  \u003e If _acceptsContext_ is `true`, _compile_ will be called with one additional parameter before the callback: the [context](#context-layouts-and-partials). That makes the _compile_ function look like: `function(data, filename, options, context, callback)`. This might be useful if your processor has some way of using the context. For example, the [pug](https://github.com/bmatcuk/pug-brunch-static) processor exposes the context as local variables for use in the pug template. Unfortunately, context is not passed to partials because of the way they are compiled.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmatcuk%2Fhtml-brunch-static","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbmatcuk%2Fhtml-brunch-static","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbmatcuk%2Fhtml-brunch-static/lists"}