{"id":21569158,"url":"https://github.com/ayarcohaila/taft","last_synced_at":"2026-04-09T12:00:41.256Z","repository":{"id":122005221,"uuid":"127712031","full_name":"ayarcohaila/taft","owner":"ayarcohaila","description":"Generate static html files from Handlebars files with YAML front matter","archived":false,"fork":false,"pushed_at":"2023-05-30T14:21:25.000Z","size":188,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-01-24T12:28:16.395Z","etag":null,"topics":["expressjs","html","nodejs","template","yaml"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ayarcohaila.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-02T06:19:16.000Z","updated_at":"2023-05-30T14:21:44.000Z","dependencies_parsed_at":null,"dependency_job_id":"f4acd63d-2ddb-458c-b96e-f5406ff7d295","html_url":"https://github.com/ayarcohaila/taft","commit_stats":null,"previous_names":["ayarcohaila/taft"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarcohaila%2Ftaft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarcohaila%2Ftaft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarcohaila%2Ftaft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ayarcohaila%2Ftaft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ayarcohaila","download_url":"https://codeload.github.com/ayarcohaila/taft/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244166640,"owners_count":20409177,"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":["expressjs","html","nodejs","template","yaml"],"created_at":"2024-11-24T11:06:55.890Z","updated_at":"2025-12-31T00:16:41.587Z","avatar_url":"https://github.com/ayarcohaila.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Taft\n\nGenerate static html files from Handlebars files with YAML front matter.\n\nIntended as a pandoc-like tool for building a simple page, or even for generating basic static websites, Taft is lightning fast, has a great command-line tool, and works for building many files or just one.\n\n### Installing\n\nTaft works great installed either locally or globally.\n\n````\nnpm install [-g] taft\n````\n\n(If you install locally, use `node_modules/.bin/taft` as the command instead of `taft` in the examples.)\n\n## command line\n\n### Basics\n\nSay you have this file. It's handlebars with yaml front matter.\n\n````handlebars\n---\ncauldronStatus: bubbling\nworkplace: cavern\nscript: magic-spells.js\n---\n\u003cp\u003eThe cauldron in my {{workplace}} is {{cauldronStatus}}.\u003c/p\u003e\n\u003cscript src=\"{{script}}\"\u003e\u003c/script\u003e\n````\n\nRun this command:\n````\ntaft source/page1.hbs \ntaft building source/page1.hbs\n\u003cp\u003eThe cauldron in my cavern is bubbling.\u003c/p\u003e\n\u003cscript src=\"magic-spells.js\"\u003e\u003c/script\u003e\n````\n\nBy default, output goes to stdout and status messages output to stderr, so one can safely pipe the result.\n\nSpecify a single output file with `--output` or `-o`:\n````\ntaft source/page1.hbs -o build/page1.html\nbuild/page1.html\n````\n\nTo generate more than one file, pass a destination directory.\n````\ntaft source/page1.hbs source/page2.hbs 'other/*.hbs' --dest-dir build/\ntaft building source/page1.hbs\nbuild/page1.html\ntaft building source/page2.hbs\nbuild/page2.html\ntaft building other/more.hbs\nbuild/more.html\n````\n\nRead from stdin by giving '-' as the file name.\n\n````\ncat source/page1.hbs | taft - \u003e build/page1.html\n````\n\n#### Magic keys in your YAML front matter\n\nTaft pays special attention to some keys in a page's YAML front matter: *ext*, *layout* and *published*. If `published: false`, then the page won't be built. Read on for details on the other two keys!\n\n### Command line options\n\n````\n    -H, --helper \u003cfile\u003e          js file that exports an object containing handlebars helpers\n    -p, --partial \u003cfile\u003e         Handlebars partial\n    -d, --data \u003cdata\u003e            JSON, YAML or INI file or data (stdin with '-' or 'key:-')\n    -t, --layout \u003cfile\u003e          Handlebars template file\n    -y, --default-layout \u003cname\u003e  use this layout as default\n    -o, --output \u003cpath\u003e          output path\n    -D, --dest-dir \u003cpath\u003e        output directory (mandatory if more than one file given)\n    -C, --cwd \u003cpath\u003e             save files relative this directory\n    -e, --ext \u003cstring\u003e           output file extension (default: html)\n    -v, --verbose                output some debugging information\n    -s, --silent                 don't output anything\n````\n\nA quick run-down:\n\n* `--default-layout`: The basename of the layout to use for pages with no layout given. By default, there is no default layout.\n* `--ext`: By default when using `--dest-dir`, files are saved as '.html'. This option specifies another extension. This will be overridden if the file has an `ext` key in its YAML front matter.\n* `--cwd`: When used in combination with `--dest-dir`, files will be saved relative to `--cwd`. For example, `--cwd=src/pages --dest-dir build` will save `src/pages/page.html` to `build/page.html`.\n\nThe following sections give details about the main options: `--data`, `--helper`, `--layout` and `--partial`. You'll find that a complex Taft command can get very long. That's OK! Use a Makefile to tract and reproduce commands.\n\n### Layouts\nUse a layout (aka template) to wrap a file with content. The layout should use the `{{\u003e body}}` helper to refer to the content.\n\nYou can register as many layouts as you like with Taft. However, they should not share basenames (e.g. `spooky/example.handlebars' and `scary/example.handlebars`).\n\nThe YFM data from the content page will be available in the layout. If there's a conflict, use the 'page' object.\n````handlebars\n---\nworkplace: haunted wood\nscript: main.js\n---\n\u003cp\u003eNotes from the {{page.workplace}} and the {{workplace}}.\u003c/p\u003e\n{{\u003e body}}\n\u003cscript src=\"{{page.script}}\"\u003e\u003c/script\u003e\n\u003cscript src=\"{{script}}\"\u003e\u003c/script\u003e\n````\n````\ntaft --layout layouts/template.hbs source/page1.hbs \u003e build/page1.html\n````\n````html\n\u003cp\u003eNotes from the cavern and the haunted wood.\u003c/p\u003e\n\u003cp\u003eThe cauldron in my cavern is bubbling.\u003c/p\u003e\n\u003cscript src=\"magic-spells.js\"\u003e\u003c/script\u003e\n\u003cscript src=\"main.js\"\u003e\u003c/script\u003e\n````\n\n````yaml\n---\n# source/page1.hbs\n# The layout for this page will be 'layouts/default.hbs'.\ntitle: My Favorite Encantations\n---\nEncantations...\n````\n````yaml\n---\n# source/page2.hbs\n# The layout for this page will be 'layouts/potions.hbs'.\n# Note that Taft allows you to just specify the base name of the file.\n# Don't expect things to work correctly if you have two layouts with the same basename\ntitle: Special Potions\nlayout: potions\n---\nPotions...\n````\n````yaml\n---\n# source/page3.hbs\n# This page will be built without a layout.\nlayout: none\ntitle: Super-Special Page\n---\nSpecial Stuff...\n````\n\n#### Default layouts\n\nOne can take advantage of a default layout one of three ways: Specify it explicity with the `--default-layout` option, Have a layout file named `default.*`, or only register one layout.\n\nIf you have a default layout but want to turn it off for a page, put `layout: false` in the YAML front matter.\n\n````\ntaft --layout layouts/default.hbs --layout layouts/potions.hbs \n    source/page1.hbs source/page2.hbs source/page3.hbs -C _source -D build\n````\n\n### Partials\nTaft will register partials from one or more files. Unlike with layouts, all of the partials must be parsed before pages can be built, so registering many partials may slow down your build.\n\n````\n# Register the partial {{\u003e fun}}\ntaft --partial partials/fun.hbs source/page1.hbs \u003e build/page1.html\ntaft building source/page1.hbs\n\n# Register the all the partials in partials/\ntaft --partial 'partials/*.hbs' source/page1.hbs \u003e build/page1.html\ntaft building source/page1.hbs\n````\n\n### Helpers\n\nTaft will register helpers for you. You pass it a file that `exports` a helper, or the name of a NPM helper module, Taft will register it to Handlebars.\n\n````\ntaft --helper helpers/magic.js source/page1.hbs \u003e build/page1.hbs\n````\n\nThe [helpers](https://github.com/helpers) project has many useful helpers, the related repo [template-helpers](https://github.com/jonschlinkert/template-helpers) collects many of them.\n````\nnpm install --save-dev template-helpers\ntaft --helper template-helpers source/page1.hbs \u003e build/page1.hbs\n````\n\nIf you're using a custom file, you can either export a function or an object containing several functions. In the former format, the function will be called with two arguments: `Handlebars` and `Taft.options`. In the latter format, the key of each function is the name of the helper.\n\n````javascript\n// This will be available in Handlebars as '{{magic}}'\n\nmodule.exports = function(Handlebars, options) {\n    Handlebars.registerHelper('magic', function(){\n        /* do stuff */\n    });\n}\n````\n\n````javascript\n// {{whiteMagic}} and {{blackMagic}}\n\n// Use your favorite node module\nvar spells = require('spells');\n\nmodule.exports = {\n    whiteMagic: function() { /* do stuff */ },\n\n    blackMagic function() { /* do bad stuff */ }\n};\n````\n\nNote that helpers must be installed in the same scope that you're running `Taft`. If you're using a global copy of taft, you'll need to install the helper globally. If you don't want to pollute the global space, or want to track everything, use a local copy of taft (`node_modules/.bin/taft`).\n\n\u003c!-- Taft comes packaged with the helpers in the [handlebars-helpers](https://github.com/assemble/handlebars-helpers) library. --\u003e\n\n### Data\n\nUse the `--data` flag to specify sources of data for Taft to read in. Use INI, YAML, JSON, or YAML front matter files. Taft will read data from files, or from stdin input in those formats. Use '-' as the file name to read from stdin.\n\n````\ntaft --data data/spooky.yaml source/page1.hbs \u003e build/page1.hbs\necho '{\"workplace\": \"haunted forest\"}' | taft --data - source/page2.hbs \u003e build/page2.hbs\n````\n\nIn the first example above, data in the file `data/spooky.yaml` can be accessed via the object `{{spooky}}`.\n\nUse globs to read in multiple data files at once. If the `data` directory contains `spooky.yaml` and `scary.yaml`:\n````\ntaft --data data/*.yaml source/page.hbs \u003e build/page.hbs\n````\n````handlebars\nscary variable 'ghost': {{ spooky.ghost }}\nscary variable 'monster': {{ scary.monster }}\n````\n\nYou can even specify an INI/JSON/YAML string as the option to the `--data` flag. This isn't terribly useful, but it's a free side-effect of reading from stdin.\n```\ntaft --data 'cool=true' source/page.hbs\ntaft --data '{\"cool\": true}' source/page.hbs\n```\n\n#### Data prefixes\n\nPrefixes can be used to place data read from file globs or stdin in a named object. For example:\n\nIn this example, `{{laughs}}` will be a list containing \"guffaw\" and \"cackle\":\n````\necho '[\"guffaw\", \"cackle\"]' | taft --data laughs:- source/page.hbs \u003e build/page.hbs\n````\n````handlebars\n{{#laughs}}\n    // do stuff\n{{/laugh}}\n````\n\nHere, all of the files that match the pattern `data/cheer/*.yaml` will be placed in the list `{{cheer}}`:\n````\ntaft --data 'cheer:data/cheer/*.yaml' source/index.hbs \u003e build/page.hbs\n````\nIf might be used like this:\n````handlebars\n{{#each cheer}}\n    \u003cli\u003e{{title}}: {{description}}\u003c/li\u003e\n{{/cheer}}\n````\n\nNote that you cannot provide a prefix for a single file, or a JSON or YAML string passed to `--data`.\n\n## Environment variables and globals\n\nThe `taft` command line tool adds your environment variables to a variable called ENV.\n```handlebars\n{{#if ENV.DEVELOPMENT}}\nThe path is: {{ENV.PATH}}\n{{/if}}\n```\n```\n# Will print PATH\nDEVELOPMENT=1 taft source/page.hbs\n# Won't print the PATH\nDEVELOPMENT= taft source/page.hbs\n```\n\nThe command line tool also adds some useful values to a `TAFT` global. The first four are the same for every page per run, the last is per-page:\n\n````javascript\nTAFT = {\n    version: '0.4.11'       // current Taft version\n    cwd: 'tests',           // --cwd value\n    destDir: 'output',      // --dest-dir value \n    ext: 'html',            // --ext value\n    output: 'output.html',  // --output value, or destination file if using --dest-dir and --cwd\n    file: 'pages/test.html' // output file path (not including destDir)\n}\n````\n\n### About specifying files\n\nIf you pass a glob (a path with a wildcard) to `--partial`, `--data`, `--layout` or `--helper`, make sure to enclose it in single quotes, or else your shell will expand it, and Taft will interpret the files after the first one as pages.\n\n````\ntaft --partial 'partials/*' source/page1.hbs\n````\n````\ntaft --data 'data/*.{yaml,json}' source/page1.hbs\n````\n\nThe `--partial`, `--data`, `--layout`, and `--helper` options are repeatable:\n````\ntaft --partial fun.hbs --partial cool.hbs source/page1.hbs\n````\n````\ntaft --data newt.ini --data 'frog-*.yaml' source/page1.hbs\n````\n\n## API\n\nTaft is designed to use on the command line, but it has a simple API. Layouts, partials, helpers can be passed a list of files or globs, or a single filename as a string. Javascript objects are also acceptable for the data option.\n````javascript\nvar Taft = require('taft');\n\nvar options = {\n    layouts: ['layout.hbs']\n    partials: 'layout.partial'\n    data: [{\"key\": \"foo\"}, 'data.json'],\n    helpers: 'helper.js',\n    defaultLayout: 'layout.hbs'\n};\nvar taft = new Taft(options);\n\n// returns a Content object, which is just a String\n// that possibly has two additional properties:\n// ext - the extension the file wants to have\n// source - the path to the source file \n\nvar result = taft.build('source/page1.hbs');\n````\n\nTaft also comes with chainable methods for adding layouts, helpers, data or partials. These can take the same arguments as the options. The above and below blocks of code are equivalent.\n\n````javascript\nvar taft = new Taft()\n    .layouts('layout.hbs')\n    .helpers(['helpers.js'])\n    .data([{\"key\": \"foo\"}, 'data.json'])\n    .partials(['layout.partial'])\n    .defaultLayout('layout.hbs');\n\nvar result = taft.build('source/page1.hbs');\n````\n\n### Shorthand\n\nFor a super-quick build of a single file, use the `Taft.taft` method:\n\n````javascript\nvar Taft = require('taft');\n\nvar options = {\n    layouts: ['layout.hbs']\n}\n\n// returns a string containing the result\nvar result = Taft.taft('source/page1.handlebars', options);\n````\n\n## License\n\nTaft is available under the GNU General Public License. It comes with absolutely no warranty. See LICENSE for more.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayarcohaila%2Ftaft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fayarcohaila%2Ftaft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fayarcohaila%2Ftaft/lists"}