{"id":13492596,"url":"https://github.com/kizu/bemto","last_synced_at":"2025-05-16T03:05:55.175Z","repository":{"id":58219026,"uuid":"4469696","full_name":"kizu/bemto","owner":"kizu","description":"Smart mixins for writing BEM in Pug","archived":false,"fork":false,"pushed_at":"2024-05-24T15:06:19.000Z","size":115,"stargazers_count":439,"open_issues_count":20,"forks_count":66,"subscribers_count":35,"default_branch":"master","last_synced_at":"2025-05-08T13:15:21.772Z","etag":null,"topics":["bem","html","pug"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kizu.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":"Code_of_Conduct.md","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":"2012-05-28T10:54:45.000Z","updated_at":"2025-03-02T14:28:38.000Z","dependencies_parsed_at":"2024-06-18T13:59:31.428Z","dependency_job_id":"41f771d2-f8d5-4418-adc4-1b60c5db2d5c","html_url":"https://github.com/kizu/bemto","commit_stats":{"total_commits":114,"total_committers":12,"mean_commits":9.5,"dds":0.5614035087719298,"last_synced_commit":"f062d746d9c1076fbbc913b2bba4dfa4e1cc7733"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kizu%2Fbemto","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kizu%2Fbemto/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kizu%2Fbemto/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kizu%2Fbemto/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kizu","download_url":"https://codeload.github.com/kizu/bemto/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459088,"owners_count":22074605,"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":["bem","html","pug"],"created_at":"2024-07-31T19:01:07.386Z","updated_at":"2025-05-16T03:05:50.166Z","avatar_url":"https://github.com/kizu.png","language":"HTML","funding_links":[],"categories":["HTML","Tools"],"sub_categories":["Template engines"],"readme":"# Bemto — mixins for writing [BEM][]-style code for [Pug][] [![Build Status][build]][build-link] [![NPM version][version]][version-link]\n\n[BEM]: http://bem.github.com/bem-method/pages/beginning/beginning.en.html\n[Pug]: https://pugjs.org/\n\n[build]: https://travis-ci.org/kizu/bemto.png?branch=master\n[build-link]: https://travis-ci.org/kizu/bemto\n[version]: https://badge.fury.io/js/bemto.pug.png\n[version-link]: http://badge.fury.io/js/bemto.pug\n\n## Table of Contents\n\n1. [Install \u0026 Use](#install--use)\n2. [Features](#features)\n    - [Blocks](#blocks)\n    - [Elements](#elements)\n    - [Modifiers](#modifiers)\n    - [Changing the tag name](#changing-the-tag-name)\n    - [Attributes](#attributes)\n    - [Context](#context)\n    - [Redefining tag's metadata](#redefining-tags-metadata)\n\n3. [Settings](#settings)\n    - [Adding Prefix](#adding-prefix)\n    - [Setting for Element syntax](#setting-for-element-syntax)\n    - [Setting for Modifier syntax](#setting-for-modifier-syntax)\n    - [Setting for allowing nested elements](#setting-for-allowing-nested-elements)\n    - [Scope for the settings](#scope-for-the-settings)\n    - [Setting for the output syntax of the elements/modifiers](#setting-for-allowing-nested-elements)\n\n\n4. [Using for building complex mixins](#using-for-building-complex-mixins)\n\n## Install \u0026 Use\n\n### Cloning\n\n1. Clone `bemto` somewhere to your project:\n\n    ```sh\n    git clone git://github.com/kizu/bemto.git\n    ```\n2. Include it in your `.pug` project:\n\n    ```Pug\n    include bemto/bemto.pug\n    ```\n\n3. Use it:\n\n    ```Pug\n    +b.block1\n      +e.element1 Foo\n      +b.block2\n        +e.A(href=\"#bar\").element Bar\n      +e.element2 Baz\n    ```\n\n    would render to something like\n\n    ```HTML\n    \u003cdiv class=\"block1\"\u003e\n      \u003cdiv class=\"block1__element1\"\u003e\n        Foo\n      \u003c/div\u003e\n      \u003cdiv class=\"block2\"\u003e\n        \u003ca class=\"block2__element\" href=\"#bar\"\u003eBar\u003c/a\u003e\n      \u003c/div\u003e\n      \u003cdiv class=\"block1__element2\"\u003e\n        Baz\n      \u003c/div\u003e\n    \u003c/div\u003e\n    ```\n\n## Features\n\n### Blocks\n\n“Block” is the main thing there. It creates the block from the first passed class and creates the context for all nested elements.\n\nYou can create block calling the `b` mixin with some class attached to it:\n\n```Pug\n+b.foo bar\n```\n\nThat would render as\n\n```HTML\n\u003cdiv class=\"foo\"\u003ebar\u003c/div\u003e\n```\n\nWhile the simple block's syntax, of course, is harder than the simple Pug's tags, the main point is to create the contexts for elements.\n\n### Elements\n\n“Element” is a accessory element of the block. You can read on the concept of the elements in the [bem methodology](http://bem.github.com/bem-method/pages/beginning/beginning.en.html#Element), or in the [great article by Nicolas Gallagher](http://nicolasgallagher.com/about-html-semantics-front-end-architecture/) (see the “Structured class names” part). Elements often are written using the block's name plus element's name with some separator (often `__` or `-`) in-between.\n\nBemto gives a convenient way to declare the elements: just use the `e` mixin inside any block context:\n\n```Pug\n+b.foo\n  +e.bar baz\n```\n\nThis would render like\n\n```HTML\n\u003cdiv class=\"foo\"\u003e\n  \u003cdiv class=\"foo__bar\"\u003ebaz\u003c/div\u003e\n\u003c/div\u003e\n```\n\n#### Context of the element\n\nNote that bemto uses the first classname of the block as a context for further elements. If you'd like to use another class without changing the order, you can mark it with `__` in the end:\n\n```Pug\n+b.foo.bar__\n  +e.baz\n```\n\nThis way instead of `foo` bemto would base the nested elements from the `bar`:\n\n```HTML\n\u003cdiv class=\"foo bar\"\u003e\n  \u003cdiv class=\"bar__baz\"\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Modifiers\n\n“Modifier” is a state of the block or element. It is often written with the addition of it's type and/or value after the single underscore like `block_mode_foo` or just `block_foo`. However, at the most cases, the block must contain either the original block/element's class, either the modifier class.\n\nBemto makes it easy to write such modifiers, 'cause you don't need now to write the same block's name twice:\n\n```Pug\n+b.block_foo bar\n```\n\nBecomes\n\n```HTML\n\u003cdiv class=\"block block_foo\"\u003ebar\u003c/div\u003e\n```\n\nSee? You write just `.block_foo` but by fact get the `.block.block_foo` instead!\n\nBut what if you need to have more than one modifier on one block or element? Bemto have a way to do so: add a class to your block or element starting with a modifier token:\n\n```Pug\n+b.block_foo._bar._baz\n  +e.element_type_lol._mode_moddy Blah\n```\n\nand that would render as\n\n```HTML\n\u003cdiv class=\"block block_foo block_bar block_baz\"\u003e\n  \u003cdiv class=\"block__element block__element_type_lol block__element_mode_moddy\"\u003e\n    Blah\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\nYou can also use shorter modifier syntax like `class=\"block -modifier\"` (but only when this syntax won't be used for delimiting full modifiers or elements).\n\n```Pug\n+b.-foo.-bar.-baz\n```\n\nthis would render to\n\n```HTML\n\u003cdiv class=\"block -foo -bar -baz\"\u003e\n\u003c/div\u003e\n```\n\n\n### Changing the tag name\n\nBy default the blocks and elements render as `div`s. You can change it by passing the desired tag name as the first class in uppercase:\n\n```Pug\n+b.SPAN.foo bar\n```\n\nOr by passing an `options` object with a `tag` param:\n\n```Pug\n+b({tag: 'span'})foo bar\n```\n\nEither way would render as\n\n```HTML\n\u003cspan class=\"foo\"\u003ebar\u003c/span\u003e\n```\n\n### Attributes\n\nLike any Pug tag or mixin, blocks and elements can take attributes that would go to the desired tags:\n\n```Pug\n+b.foo(title=\"Oh, it's a title\")\n  +e.A.bar(href='#baz') baz\n```\n\nwould render like\n\n```HTML\n\u003cdiv class=\"foo\" title=\"Oh, it's a title\"\u003e\n  \u003ca class=\"foo__bar\" href=\"#baz\"\u003ebaz\u003c/a\u003e\n\u003c/div\u003e\n```\n\n#### Automatic attributes\n\nThere are some tags like `img` that must have at least one attribute set. Bemto would create attributes with some predefined values for such tags. So, for images this code — `+b.image(src=\"foo.png\")` would render `\u003cimg alt=\"\" class=\"image\" src=\"foo.png\"/\u003e` — you can see that in that case there is the added empty `alt`.\n\nAlso, in some cases there is a need to adjust some attributes according to other ones. For `img` if the `alt` is set, but the `title` is not we'd need to set it to empty, 'cause there'd be a inconsistency between browsers (IE would show the `title` bubble for `alt`). And from the other side, if there is only `title` set in an image, we'd need to clone it to `alt`. Bemto do all those things.\n\n### Context\n\nLook at the previous example: you have there some excess code that you can throw away. It's the `('a')` part — as long as you set the `href` attribute, the block would automagically become the link. Also, there are other tags that you can omit: `li` in `ul` or `ol` context, or `span` in any already inline context.\n\nSo, here is a bigger example:\n\n```Pug\n+b.UL.list\n  +b.list-item\n    +e.link(href=\"foo\")\n      +e.text foo\n  +b.list-item\n    +e.link(href=\"bar\")\n      +e.text bar\n```\n\nWould render to\n\n```HTML\n\u003cul class=\"list\"\u003e\n  \u003cli class=\"list-item\"\u003e\n    \u003ca class=\"list-item__link\" href=\"foo\"\u003e\n      \u003cspan class=\"list-item__text\"\u003efoo\u003c/span\u003e\n    \u003c/a\u003e\n  \u003c/li\u003e\n  \u003cli class=\"list-item\"\u003e\n    \u003ca class=\"list-item__link\" href=\"bar\"\u003e\n      \u003cspan class=\"list-item__text\"\u003ebar\u003c/span\u003e\n    \u003c/a\u003e\n  \u003c/li\u003e\n\u003c/ul\u003e\n```\n\nFor now that's all, but there would be other contexts in the future of bemto.\n\n### Redefining tag's metadata\n\nIn a case you'd like some tag to set a different context, i.e. to override it's content_type, you can use a `metadata` option for the block/element. For example, if you'd like a link to have block context, you can redefine it in this way:\n\n```Pug\n+b({ metadata: { content_type: 'block' } }).A.foo\n  +e.bar\n```\n\nwould render as\n\n``` html\n\u003ca class=\"foo\"\u003e\n\u003cdiv class=\"foo__bar\"\u003ebaz\n\u003c/div\u003e\u003c/a\u003e\n```\n\n## Settings\n\nThere are some settings you can set for different syntaxes of BEM.\n\nFor doing so, you must set them after including the `bemto` like this:\n\n```Pug\n-\n  set_bemto_settings({\n    prefix: '',\n    element: '__',\n    modifier: '_'\n  })\n```\n\nHere you can see all available settings with their default values.\n\n### Adding Prefix\n\nIf you'd like to prefix all your bemto-generated blocks, you can set the `prefix` setting to a String or an Object.\n\n#### Strings for prefix setting\n\nIf you'd set a string, it would be just prepended to the names of all blocks:\n\n```Pug\n- set_bemto_settings({ prefix: 'b-' })\n\n+b.block\n  +e.element foo\n\n```\n\nand that would then render as\n\n```HTML\n\u003cdiv class=\"b-block\"\u003e\n  \u003cdiv class=\"b-block__element\"\u003e\n    foo\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\nNote that if you had already used this prefix in a classname, it won't be added, so you won't have occasional duplicated prefixes.\n\n#### Objects for prefix setting\n\nIf you'd want to have more control over prefixes, you can use a special object instead of a string:\n\n``` Pug\n-\n  set_bemto_settings({\n    prefix: {\n      '': 'b-',\n      'js-': true,\n      'is-': 'is-',\n      'global-': '',\n      'nope-': false,\n      'sc-': 'shortcut-'\n    }\n  })\n```\n\nLook at the above example, it have all the variations the prefix object accepts:\n\n- The empty string for key works the same as a string setting: you'd get the value for this key prepended for all classnames without detected prefixes.\n\n- If a value for any key is `true`, this prefix would be always treated as such and won't be prepended by other prefixes.\n\n- If a value for a key is `false` or an empty string, the classnames with this prefix would be rendered without it.\n\n- In other cases, where the key and the value are both strings, all the key prefixes in the source code would be replaced with the value ones, and also all of those prefixes would be treated as registered ones, so you wouldn't add other prefixes for them.\n\n### Setting for Element syntax\n\nIf you don't like the default elements syntax with the `__` delimiter, you can set using the `element` setting:\n\n```Pug\n- set_bemto_settings({ element: '-' })\n\n+b.block\n  +e.element foo\n\n```\n\nthis would render to\n\n```HTML\n\u003cdiv class=\"block\"\u003e\n  \u003cdiv class=\"block-element\"\u003e\n    foo\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Setting for Modifier syntax\n\nIf you'd like to use different modifier syntax, like the one Nicolas Gallagher mentioned in [his article](http://nicolasgallagher.com/about-html-semantics-front-end-architecture/), you can use the `modifier` setting:\n\n```Pug\n- set_bemto_settings({ modifier: '--' })\n\n+b.block--modifier-name.--other-modifier foo\n```\n\nand that would expand to\n\n```HTML\n\u003cdiv class=\"block block--modifier-name block--other-modifier\"\u003e\n  foo\n\u003c/div\u003e\n```\n\n### Setting for allowing nested elements\n\nThere can be cases when you could want to make elements of elements, i.e. when using element names instead of block names:\n\n```Pug\n+b.block-element\n  +e.element2\n```\n\nrenders by default to\n\n```HTML\n\n\u003cdiv class=\"foo__bar\"\u003e\n  \u003cdiv class=\"foo__baz\"\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\nIf you'd like to have `foo__bar__baz` in the output instead, you can set the `flat_elements` to `false`:\n\n```Pug\n- set_bemto_settings({ flat_elements: false })\n\n+b.foo__bar\n  +e.baz\n```\n\nThis would render with the nested element:\n\n```HTML\n\u003cdiv class=\"foo__bar\"\u003e\n  \u003cdiv class=\"foo__bar__baz\"\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Scope for the settings\n\nIf you'll need to have some settings just in a certain scope, you can wrap your code in `bemto_scope` mixin, passing your desired settings right into it:\n\n```Pug\n+b.foo_bar\n  +bemto_scope({\n      prefix: 'b-',\n      element: '-',\n      modifier: '--'\n    })\n    +b.nnnn\n      +e.mmmm--kkkk\n  +e.baz\n```\n\nWould render as\n\n```HTML\n\u003cdiv class=\"foo foo_bar\"\u003e\n  \u003cdiv class=\"b-nnnn\"\u003e\n    \u003cdiv class=\"b-nnnn-mmmm b-nnnn-mmmm--kkkk\"\u003e\n    \u003c/div\u003e\n  \u003c/div\u003e\n  \u003cdiv class=\"foo__baz\"\u003e\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\n### Setting for the output syntax of the elements/modifiers\n\nIf you'd like to use different syntax of the element/modifier delimiter in Pug source and the html output, you can use the `ouput_element` and `output_modifier` settings, otherwise the same delimiter as in the `element` and `modifier` settings would be used.\n\n```Pug\n-\n  set_bemto_settings({\n    element: '-',\n    modifier: '--',\n    output_element: '__',\n    output_modifier: '_'\n  })\n\n+b.block.block2-\n  +e.element--modifier foo\n```\n\nwould output\n\n```HTML\n\u003cdiv class=\"block block2\"\u003e\n  \u003cdiv class=\"block2__element block2__element_modifier\"\u003efoo\n  \u003c/div\u003e\n\u003c/div\u003e\n```\n\nYou can see how the source uses the `-` for element and `--` for modifier, but the result gets `__` and `_` instead.\n\n### Setting for delimiters between classnames\n\nIf you'd like to have extra delimieters between the rendered classnames for clarity, you can use a `class_delimiter` setting:\n\n``` Pug\n- set_bemto_settings({ class_delimiter: '|' })\n\n+b.foo.bar_baz\n```\n\nWould be rendered as\n\n``` HTML\n\u003cdiv class=\"foo | bar | bar_baz\"\u003e\n\u003c/div\u003e\n```\n\nNote that there would be always added spaces around the given delimiter, so you don't need to include them in the setting's value.\n\n## Using for building complex mixins\n\nThis is somewhat obvious, but I must mention that the bemto blocks would be great for using as the bricks for building more complex blocks. The Pug mixins work in the way where you can translate any attributes through to the any inner blocks. So you can do this:\n\n```Pug\nmixin link(url)\n  +b.SPAN.link(href=url)\u0026attributes(attributes)\n    block\n```\n\nAnd then use it in this way:\n\n```Pug\n+link('#Foo') Foo\n\n+link('https://github.com')._external Github\n\n+link('http://kizu.ru').url(rel=\"me\") Here I am\n\n+link Ah, I'm not a link\n\n+link('https://github.com')\n  +e.icon(src=\"http://favicon.yandex.net/favicon/github.com\")\n  +e.text Github\n```\n\nAnd that would render to\n\n```HTML\n\u003ca class=\"link\" href=\"#Foo\"\u003eFoo\u003c/a\u003e\n\n\u003ca class=\"link link_external\" href=\"https://github.com\"\u003eGithub\u003c/a\u003e\n\n\u003ca class=\"link url\" href=\"http://kizu.ru\" rel=\"me\"\u003eHere I am\u003c/a\u003e\n\n\u003cspan class=\"link\"\u003eAh, I'm not a link\u003c/span\u003e\n\n\u003ca class=\"link\" href=\"https://github.com\"\u003e\n  \u003cimg alt=\"\" role=\"presentation\" class=\"link__icon\" src=\"http://favicon.yandex.net/favicon/github.com\"/\u003e\n  \u003cspan class=\"link__text\"\u003eGithub\u003c/span\u003e\n\u003c/a\u003e\n```\n\nThere you can see almost all of the bemto features that can be used for any mixin with `attributes` variable attached to any inner bemto block inside of it.\n\n- - -\n\nTo be continued!\n\nIf you'd like to follow on the bemto progress, [follow me on twitter](https://twitter.com/kizmarh/).\n\n- - -\n\nCopyright (c) 2012 Roman Komarov \u003ckizu@kizu.ru\u003e\n\nPermission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkizu%2Fbemto","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkizu%2Fbemto","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkizu%2Fbemto/lists"}