{"id":16672027,"url":"https://github.com/posthtml/posthtml-extend","last_synced_at":"2025-08-20T11:23:50.497Z","repository":{"id":3161958,"uuid":"48585725","full_name":"posthtml/posthtml-extend","owner":"posthtml","description":"Template extending (Jade-like)","archived":false,"fork":false,"pushed_at":"2023-03-15T01:23:23.000Z","size":1593,"stargazers_count":46,"open_issues_count":10,"forks_count":9,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-10-29T21:06:04.989Z","etag":null,"topics":["posthtml"],"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/posthtml.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":".github/funding.yml","license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null},"funding":{"github":null,"patreon":"posthtml","open_collective":"posthtml","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2015-12-25T16:26:13.000Z","updated_at":"2024-10-12T19:05:36.000Z","dependencies_parsed_at":"2023-07-06T08:33:29.074Z","dependency_job_id":null,"html_url":"https://github.com/posthtml/posthtml-extend","commit_stats":{"total_commits":101,"total_committers":12,"mean_commits":8.416666666666666,"dds":0.7524752475247525,"last_synced_commit":"98810027c19becb21d2537f1ef6bb37a34ddf92f"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-extend","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-extend/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-extend/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-extend/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/posthtml","download_url":"https://codeload.github.com/posthtml/posthtml-extend/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243501456,"owners_count":20300893,"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":["posthtml"],"created_at":"2024-10-12T12:04:57.318Z","updated_at":"2025-03-15T12:30:34.351Z","avatar_url":"https://github.com/posthtml.png","language":"JavaScript","readme":"# posthtml-extend [![npm version](https://badge.fury.io/js/posthtml-extend.svg)](http://badge.fury.io/js/posthtml-extend) [![Build Status](https://travis-ci.org/posthtml/posthtml-extend.svg?branch=master)](https://travis-ci.org/posthtml/posthtml-extend)\n\n[PostHTML](https://github.com/posthtml/posthtml) plugin that allows a template to extend (inherit) another templates ([Jade-like](http://jade-lang.com/reference/inheritance/)).\n\n\n## Usage\nLet's say we have a base template:\n\n`base.html`\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003e\u003cblock name=\"title\"\u003e — Github\u003c/block\u003e\u003c/title\u003e\n    \u003c/head\u003e\n\n    \u003cbody\u003e\n        \u003cdiv class=\"content\"\u003e\n           \u003cblock name=\"content\"\u003e\u003c/block\u003e\n        \u003c/div\u003e\n        \u003cfooter\u003e\n            \u003cblock name=\"footer\"\u003efooter content\u003c/block\u003e\n        \u003c/footer\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\nNow we can inherit this template. All defined blocks inside `\u003cextends\u003e` will\nreplace the blocks with the same name in the parent template. If the block is not\ndefined inside `\u003cextends\u003e` its content in the parent template remains the same.\n\nIn the example the blocks `title` and `content` will be replaced and\nthe block `footer` will remain unchanged:\n```js\nvar posthtml = require('posthtml');\nvar html = `\u003cextends src=\"base.html\"\u003e\n      \u003cblock name=\"title\"\u003eHow to use posthtml-extend\u003c/block\u003e\n      \u003cblock name=\"content\"\u003eRead the documentation\u003c/block\u003e\n  \u003c/extends\u003e`;\n\nposthtml([require('posthtml-extend')({\n    encoding: 'utf8', // Parent template encoding (default: 'utf8')\n    root: './' // Path to parent template directory (default: './')\n})]).process(html).then(function (result) {\n    console.log(result.html);\n});\n```\n\nThe final HTML will be:\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eHow to use posthtml-extend\u003c/title\u003e\n    \u003c/head\u003e\n\n    \u003cbody\u003e\n        \u003cdiv class=\"content\"\u003eRead the documentation\u003c/div\u003e\n        \u003cfooter\u003efooter content\u003c/footer\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n\n### Append/prepend\nIt's also possible to append and prepend block's content:\n```js\nvar posthtml = require('posthtml');\nvar html = `\u003cextends src=\"base.html\"\u003e\n      \u003cblock name=\"title\" type=\"prepend\"\u003eHow to use posthtml-extend\u003c/block\u003e\n      \u003cblock name=\"content\"\u003eRead the documentation\u003c/block\u003e\n      \u003cblock name=\"footer\" type=\"append\"\u003e— 2016\u003c/block\u003e\n  \u003c/extends\u003e`;\n\nposthtml([require('posthtml-extend')()]).process(html).then(function (result) {\n    console.log(result.html);\n});\n```\n\nThe final HTML will be:\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eHow to use posthtml-extend — Github\u003c/title\u003e\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003cdiv class=\"content\"\u003eRead the documentation\u003c/div\u003e\n        \u003cfooter\u003efooter content — 2016\u003c/footer\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### Pass data to layouts\n\nIn addition to normal html content you can also pass data as a json object to your layout file. To do this add a `locals` attribute to your `\u003cextend\u003e` and pass a json string.\n\nLike this:\n\n```js\n    var posthtml = require('posthtml');\n    var html = `\u003cextends src=\"base.html\" locals='{\"bodyclass\": \"home\"}'\u003e\n        \u003cblock name=\"content\"\u003eRead the documentation\u003c/block\u003e\n    \u003c/extends\u003e`;\n   \n    posthtml([require('posthtml-extend')()]).process(html).then(function (result) {\n        console.log(result.html);\n    });\n```\n\nNow you can easily access your data inside of your `base.html`: \n\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eHow to use posthtml-extend — Github\u003c/title\u003e\n    \u003c/head\u003e\n\n    \u003cbody class=\"{{ bodyclass }}\"\u003e\n        \u003cdiv class=\"content\"\u003e\n           \u003cblock name=\"content\"\u003e\u003c/block\u003e\n        \u003c/div\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\nThe final HTML will be:\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eHow to use posthtml-extend — Github\u003c/title\u003e\n    \u003c/head\u003e\n    \u003cbody class=\"home\"\u003e\n        \u003cdiv class=\"content\"\u003eRead the documentation\u003c/div\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\nThis behaviour can be customized with the option [`expressions`](#expressions).\n\n## Options\n\n### encoding\n\nType: `string`\\\nDefault: `utf8`\n\nThe encoding of the parent template.\n\n### plugins\n\nType: `array`\\\nDefault: `[]`\n\nYou can include [other PostHTML plugins](http://posthtml.github.io/posthtml-plugins/) in your templates.\nHere is an example of using [posthtml-expressions](https://github.com/posthtml/posthtml-expressions), which allows to use variables and conditions:\n\n```js\nvar posthtml = require('posthtml');\nvar options = {\n    plugins: [\n        require('posthtml-expressions')({ locals: { foo: 'bar'} })\n    ]\n};\nvar html = `\u003cextends src=\"base.html\"\u003e\n      \u003cif condition=\"foo === 'bar'\"\u003e\n        \u003cblock name=\"content\"\u003econtent value foo equal bar\u003c/block\u003e\n      \u003c/if\u003e\n\n      \u003cif condition=\"foo !== 'bar'\"\u003e\n          \u003cblock name=\"content\"\u003e value foo not equal bar\u003c/block\u003e\n      \u003c/if\u003e\n  \u003c/extends\u003e`;\n\nposthtml([require('posthtml-extend')(options)]).process(html).then(function (result) {\n    console.log(result.html);\n});\n```\n\nThe final HTML will be:\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eHow to use posthtml-extend — Github\u003c/title\u003e\n    \u003c/head\u003e\n    \u003cbody\u003e\n        \u003cdiv class=\"content\"\u003econtent value foo equal bar\u003c/div\u003e\n        \u003cfooter\u003efooter content — 2016\u003c/footer\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### root\n\nType: `string`\\\nDefault: `./`\n\nThe path to the root template directory.\n\n### strict\n\nType: `boolean`\\\nDefault: `true`\n\nWhether the plugin should disallow undeclared block names.\n\nBy default, the plugin raises an exception if an undeclared block name is encountered. This can be useful for troubleshooting (i.e. detecting typos in block names), but\nthere are cases where \"forward declaring\" a block name as an extension point for downstream templates is useful, so this restriction can be lifted by setting the `strict`\noption to a false value:\n\n```js\nconst extend = require('posthtml-extend');\n\nconst root = './src/html';\nconst options = { root, strict: false };\n\nposthtml([extend(options)]).then(result =\u003e console.log(result.html));\n```\n\n### slot/fill\n\nType: `string`\\\nDefault: `block`\n\nTag names used to match a content block with a block for inserting content.\n\n`base.html`\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003e\u003cslot name=\"title\"\u003e — Github\u003c/slot\u003e\u003c/title\u003e\n    \u003c/head\u003e\n\n    \u003cbody\u003e\n        \u003cdiv class=\"content\"\u003e\n           \u003cslot name=\"content\"\u003e\u003c/slot\u003e\n        \u003c/div\u003e\n        \u003cfooter\u003e\n            \u003cslot name=\"footer\"\u003efooter content\u003c/slot\u003e\n        \u003c/footer\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n```js\nvar posthtml = require('posthtml');\nvar html = `\u003cextends src=\"base.html\"\u003e\n      \u003cfill name=\"title\"\u003eHow to use posthtml-extend\u003c/fill\u003e\n      \u003cfill name=\"content\"\u003eRead the documentation\u003c/fill\u003e\n  \u003c/extends\u003e`;\n\nposthtml([require('posthtml-extend')({\n    slotTagName: 'slot',\n    fillTagName: 'fill'\n})]).process(html).then(result =\u003e console.log(result.html));\n```\n\nThe final HTML will be:\n```xml\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eHow to use posthtml-extend\u003c/title\u003e\n    \u003c/head\u003e\n\n    \u003cbody\u003e\n        \u003cdiv class=\"content\"\u003eRead the documentation\u003c/div\u003e\n        \u003cfooter\u003efooter content\u003c/footer\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### tagName\n\nType: `string`\\\nDefault: `extends`\n\nThe tag name to use when extending.\n\n```js\nvar posthtml = require('posthtml');\nvar html = `\u003clayout src=\"base.html\"\u003e\n    \u003cblock name=\"title\"\u003eUsing a custom tag name\u003c/block\u003e\n    \u003cblock name=\"content\"\u003eRead the documentation\u003c/block\u003e\n\u003c/layout\u003e`;\n\nposthtml([require('posthtml-extend')({\n    tagName: 'layout',\n})]).process(html).then(result =\u003e console.log(result.html));\n```\n\nThe final HTML will be:\n\n```html\n\u003chtml\u003e\n    \u003chead\u003e\n        \u003ctitle\u003eUsing a custom tag name\u003c/title\u003e\n    \u003c/head\u003e\n\n    \u003cbody\u003e\n        \u003cdiv class=\"content\"\u003eRead the documentation\u003c/div\u003e\n        \u003cfooter\u003efooter content\u003c/footer\u003e\n    \u003c/body\u003e\n\u003c/html\u003e\n```\n\n### expressions\n\nType: `object`\\\nDefault: `{}`\n\nThis option accepts an object to configure `posthtml-expressions`.\nYou can pre-set locals or customize the delimiters for example.\n\nHead over to the [full documentation](https://github.com/posthtml/posthtml-expressions#options) for information on every available option.\n","funding_links":["https://patreon.com/posthtml","https://opencollective.com/posthtml"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthtml%2Fposthtml-extend","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposthtml%2Fposthtml-extend","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthtml%2Fposthtml-extend/lists"}