{"id":24983662,"url":"https://github.com/posthtml/posthtml-plugin-starter","last_synced_at":"2025-04-11T20:51:24.637Z","repository":{"id":38844402,"uuid":"250537393","full_name":"posthtml/posthtml-plugin-starter","owner":"posthtml","description":"A starter project for building PostHTML plugins.","archived":false,"fork":false,"pushed_at":"2025-04-09T20:54:59.000Z","size":1628,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-09T21:39:27.265Z","etag":null,"topics":["html","html-parsing","posthtml","posthtml-plugin"],"latest_commit_sha":null,"homepage":"","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":null,"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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":null,"patreon":"posthtml","open_collective":"posthtml","ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":"mailviews.com"}},"created_at":"2020-03-27T13:09:54.000Z","updated_at":"2025-04-09T20:53:54.000Z","dependencies_parsed_at":"2024-01-04T19:03:12.568Z","dependency_job_id":"bbc85185-d6d9-4c2f-9d67-a02377454b06","html_url":"https://github.com/posthtml/posthtml-plugin-starter","commit_stats":{"total_commits":136,"total_committers":3,"mean_commits":"45.333333333333336","dds":0.375,"last_synced_commit":"bcadc38e1bd9688eb131c769969965bc554accb1"},"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-plugin-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-plugin-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-plugin-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/posthtml%2Fposthtml-plugin-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/posthtml","download_url":"https://codeload.github.com/posthtml/posthtml-plugin-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248480512,"owners_count":21110936,"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":["html","html-parsing","posthtml","posthtml-plugin"],"created_at":"2025-02-04T09:20:04.090Z","updated_at":"2025-04-11T20:51:24.609Z","avatar_url":"https://github.com/posthtml.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"150\" height=\"150\" alt=\"PostHTML\" src=\"https://posthtml.github.io/posthtml/logo.svg\"\u003e\n  \u003ch1\u003ePlugin Starter Kit\u003c/h1\u003e\n  \u003cp\u003eA starter project for PostHTML plugins\u003c/p\u003e\n\n  [![Version][npm-version-shield]][npm]\n  [![Build][github-ci-shield]][github-ci]\n  [![License][license-shield]][license]\n  [![Downloads][npm-stats-shield]][npm-stats]\n\u003c/div\u003e\n\n### About\n\nThis is a starter project for PostHTML plugins.\n\n```sh\ngit clone https://github.com/posthtml/posthtml-plugin-starter.git\n```\n\n### Features\n\n- [Async](#async-plugins) and [sync](#sync-plugins) examples\n- Supports both ESM and CJS \n- Node.js 18+\n- Tests with [`vitest`](https://vitest.dev)\n- Linting with [`biome`](https://biomejs.dev/)\n- Releases with [`np`](https://github.com/sindresorhus/np)\n- CI with GitHub Actions\n\n#### Async plugins\n\nWhen writing an async PostHTML plugin, you must return a `Promise` that resolves the current `tree`:\n\n```js\nexport default (options = {}) =\u003e tree =\u003e {\n  // Accept options and set defaults\n  options.foo = options.foo || {}\n\n  return new Promise((resolve, reject) =\u003e {\n    try {\n      // do something async\n\n      // finally, resolve the promise by returning the tree\n      resolve(tree)\n    } catch (error) {\n      reject(error)\n    }\n  })\n}\n```\n\nNote: async plugins can't be used in PostHTML's [`sync` mode](https://posthtml.org/#/core?id=posthtml-options).\n\n#### Sync plugins\n\nSynchronous plugins just need to return the `tree`.\n\nYou may use the `tree.walk` method to traverse the `tree` and handle nodes. \n\nThe handling of nodes can be a function that is passed to `tree.walk`, and which must return the node:\n\n```js\nexport default (options = {}) =\u003e tree =\u003e {\n  options.foo = options.foo || {}\n\n  const handleNodes = node =\u003e {\n    // Write your code...\n\n    // Return the node\n    return node\n  }\n\n  return tree.walk(handleNodes)\n}\n```\n\n#### Tests\n\nThe testing boilerplate includes a `process()` method which accepts 4 parameters:\n\n- `t` the test object\n- `name` the file name of the fixture/expected files, excluding extension\n- `options` any options to pass to the plugin when testing\n- `log` a boolean that turns on logging to console\n\nFor example, imagine we're writing a test that uses `/test/fixtures/skip-nodes.html`:\n\n```js\ntest('It skips nodes defined in `skipNodes` option', t =\u003e {\n  return process(t, 'skip-nodes', {skipNodes: ['a']}, true)\n})\n```\n\nAs you can see, the second parameter passed to the `process()` method is the fixture file name, without the `.html` extension.\n\n##### Testing for Errors\n\nTo test errors thrown by your plugin, use the `error()` method:\n\n```js\ntest('Syntax error', t =\u003e {\n  return error('syntax-error', err =\u003e {\n    expect(err.message).toBe('Invalid or unexpected token')\n  })\n})\n```\n\nJust like before, the first parameter passed to `error()` is the fixture file name, without the extension.\n\n#### Linting\n\nYou may configure `eslint` in `.eslintrc`. See [ESLint rules](https://eslint.org/docs/rules/) for options.\n\n#### Coverage\n\n`@vitest/coverage-v8` defaults are used, you may [configure it](https://vitest.dev/guide/coverage.html).\n\n#### Releases\n\nThe starter uses `np` for publishing to npm, take a look at its [configuration options](https://github.com/sindresorhus/np#config).\n\nWhen publishing your first release, leave `\"version\": \"0.0.0\"` in `package.json` - you will set it through `np`'s interactive UI.\n\n#### Continuous Integration\n\nGitHub Actions is used for continuous integration, and you can configure it by editing the `.github/workflows/nodejs.yml` file.\n\nA `.github/dependabot.yml` config file is also included, to help automate dependency updates.\n\n### Other notes\n\n- update shield icon URLs at the end of this file\n- edit (or remove) the issue template\n- update `package.json` fields\n- update the `LICENSE` file \n\n_Delete all of the above text, including the separator below - what follows is some boilerplate for your plugin's `README.md`._\n\n---\n\n## Introduction\n\nDescribe what your plugin does. \n\nOptionally add a short before \u0026 after example, like so:\n\nInput:\n\n```html\n\u003cdiv filter=\"uppercase\"\u003eTest\u003c/div\u003e\n```\n\nOutput:\n\n```html\n\u003cdiv\u003eTEST\u003c/div\u003e\n```\n\n## Install\n\n```\nnpm i posthtml posthtml-myplugin\n```\n\n## Usage\n\nProvide clear code samples showing how to use the plugin: \n\n```js\nimport posthtml from 'posthtml'\nimport myplugin from 'posthtml-myplugin'\n\nposthtml([\n  myplugin()\n])\n  .process('\u003cdiv filter=\"uppercase\"\u003eTest\u003c/div\u003e')\n  .then(result =\u003e console.log(result.html))\n```\n\nResult:\n\n```html\n\u003cdiv\u003eTEST\u003c/div\u003e\n```\n\n## Syntax\n\nMost PostHTML plugins use custom HTML syntax, like custom tag names or even custom attributes. If your plugin requires using custom markup, document it here.\n\nFor example:\n\n### Tag\n\nUse the `\u003cuppercase\u003e` tag to transform all text inside it:\n\n```xml\n\u003cuppercase\u003eTest\u003c/uppercase\u003e\n```\n\nThe tag is removed in the output.\n\nResult:\n\n```html\nTEST\n```\n\n### Attribute\n\nYou can use a filter by calling it as the value of the `filter` attribute:\n\n```html\n\u003cdiv filter=\"uppercase\"\u003eTest\u003c/div\u003e\n```\n\nThe `filter` attribute is removed in the output.\n\nResult:\n\n```html\n\u003cdiv\u003eTEST\u003c/div\u003e\n```\n\n## Options\n\nIf your plugin can be configured through options, explain what they do and how to use them. Make sure to specify what the defaults are.\n\nFor example:\n\n### `only`\n\nType: `array`\\\nDefault: `[]`\n\nArray of filter names to use. All other filters will be disabled.\n\n```js\nimport posthtml from 'posthtml'\nimport myplugin from 'posthtml-myplugin'\n\nposthtml([\n  myplugin({\n    only: ['uppercase', 'slugify']\n  })\n])\n  .process('\u003cdiv filter=\"uppercase\"\u003eTest\u003c/div\u003e')\n  .then(result =\u003e console.log(result.html))\n```\n\nBy default, this is set to an empty array, which means that all filters can be used. \n\n## 3\u003csup\u003erd\u003c/sup\u003e parties\n\nIf your plugin depends on third party libraries that require configuration, explain here what the user needs to do.\n\n[npm]: https://www.npmjs.com/package/posthtml\n[npm-version-shield]: https://img.shields.io/npm/v/posthtml.svg\n[npm-stats]: http://npm-stat.com/charts.html?package=posthtml\n[npm-stats-shield]: https://img.shields.io/npm/dt/posthtml.svg\n[github-ci]: https://github.com/posthtml/posthtml-plugin-starter/actions/workflows/nodejs.yml\n[github-ci-shield]: https://github.com/posthtml/posthtml-plugin-starter/actions/workflows/nodejs.yml/badge.svg\n[license]: ./license\n[license-shield]: https://img.shields.io/npm/l/posthtml.svg\n","funding_links":["https://patreon.com/posthtml","https://opencollective.com/posthtml","mailviews.com"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthtml%2Fposthtml-plugin-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fposthtml%2Fposthtml-plugin-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fposthtml%2Fposthtml-plugin-starter/lists"}