{"id":15502096,"url":"https://github.com/djm/remark-shortcodes","last_synced_at":"2025-04-14T06:20:46.638Z","repository":{"id":24957671,"uuid":"102861102","full_name":"djm/remark-shortcodes","owner":"djm","description":"A custom Markdown syntax parser for remark that adds support for shortcodes.","archived":false,"fork":false,"pushed_at":"2022-06-22T04:20:54.000Z","size":389,"stargazers_count":45,"open_issues_count":5,"forks_count":7,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-02T17:48:32.650Z","etag":null,"topics":[],"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/djm.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":"2017-09-08T12:52:26.000Z","updated_at":"2024-07-11T13:35:54.000Z","dependencies_parsed_at":"2022-08-23T06:01:09.185Z","dependency_job_id":null,"html_url":"https://github.com/djm/remark-shortcodes","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djm%2Fremark-shortcodes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djm%2Fremark-shortcodes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djm%2Fremark-shortcodes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djm%2Fremark-shortcodes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djm","download_url":"https://codeload.github.com/djm/remark-shortcodes/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248717251,"owners_count":21150389,"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-10-02T09:07:54.372Z","updated_at":"2025-04-14T06:20:46.603Z","avatar_url":"https://github.com/djm.png","language":"JavaScript","readme":"# remark-shortcodes [![NPM Package][npm-package-badge]][npm-package] [![Coverage Status][codecov-badge]][codecov]\n\nA custom Markdown syntax parser for [**remark**][remark] that adds support for shortcodes.\n\n## Update, January 2021\n\nThis package does not work with Remark v13+ due to its parser changes:\n\n* If you would like to fix that, please [see this issue](https://github.com/djm/remark-shortcodes/issues/19).\n* If you would like similiar functionality but with a different syntax - see the core-maintained [`remark-directive`](https://github.com/remarkjs/remark-directive) project.\n\n## Summary\n\n**_What are shortcodes?_** They are a way to provide hooks for macros and/or\ntemplate partials inside a markdown file. They consist of start \u0026 end blocks,\nin between which the shortcode has a name defined and an optional set of\nkey:value attributes in HTML style. They can look like this:\n\n```md\nThe example below uses the default start \u0026 end blocks that\nthis parser ships with:\n\n[[ MailchimpForm id=\"chfk2\" ]]\n\nBut they are configurable, so if you're coming from Hugo say,\nyou can set them as such:\n\n{{\u003c MailchimpForm id=\"chfk2\" \u003e}}\n```\n\n**_Why use them?_** Because sometimes you'd like to insert content inline\nwithout copy pasting raw HTML in to your Markdown file. The copy paste\napproach means that hard-to-modify code is littered throughout your\ncontent and is therefore very hard to maintain; whereas the shortcode\napproach can result in a partial being updated in only one place.\n\nBoth [Wordpress][wordpress-shortcodes] \u0026 [Hugo][hugo-shortcodes] have\nsupport for shortcodes; this parser's implementation is much closer\nto Wordpress's, as it does not support inner content or nested shortcodes\nlike Hugo does - but can actually be used for the simpler partials. It\nwas made for my use, but if you'd like to extend it to support more cases,\nplease feel free! Everyone is welcome.\n\n## AST Block: `Shortcode`\n\n`Shortcode` ([`Node`][node]) is a simple node that has an identifier and an\noptional object with string values, respresenting the attributes parsed.\n\n```idl\ninterface Shortcode \u003c: Node {\n  type: \"shortcode\";\n  identifier: string;\n  attributes: { key: string, ...}\n}\n```\n\nFor example, the following markdown:\n\n```md\n[[ MailchimpForm id=\"chfk2\" ]]\n```\n\nYields:\n\n```json\n{\n  \"type\": \"shortcode\",\n  \"identifier\": \"MailchimpForm\",\n  \"attributes\": { \"id\": \"chfk2\" }\n}\n```\n\n## Installation\n\n[npm][npm]:\n\n```bash\nnpm install --save remark-shortcodes\n```\n\n## Usage\n\nSay `example.js` looks as follows:\n\n```javascript\nvar unified = require('unified');\nvar parse = require('remark-parse');\nvar shortcodes = require('remark-shortcodes');\n\nvar markdown = 'Example paragraph\\n\\n{{\u003e MailchimpForm id=\"chfk2\" \u003c}}'\n\nvar tree = unified()\n  .use(parse)\n  // Plugin inserted below, with custom options for start/end blocks.\n  .use(shortcodes, {startBlock: \"{{\u003e\", endBlock: \"\u003c}}\"})\n  // Turn off position output for legibility below.\n  .data('settings', {position: false})\n  .parse(markdown);\n\nconsole.dir(tree, {depth: null});\n```\n\nRunning `node example` yields:\n\n```json\n{\n  \"type\": \"root\",\n  \"children\": [\n    {\n      \"type\": \"paragraph\",\n      \"children\": [{ \"type\": \"text\", \"value\": \"Example paragraph\" }]\n    },\n    {\n      \"type\": \"shortcode\",\n      \"identifier\": \"MailchimpForm\",\n      \"attributes\": { \"id\": \"chfk2\" }\n    }\n  ]\n}\n```\n\nSay `example2.js` looks as follows:\n\n```javascript\nvar unified = require('unified');\nvar parse = require('remark-parse');\nvar shortcodes = require('remark-shortcodes');\n\nvar ast = {\n  \"type\": \"root\",\n  \"children\": [\n    {\n      \"type\": \"paragraph\",\n      \"children\": [{ \"type\": \"text\", \"value\": \"Example paragraph\" }]\n    },\n    {\n      \"type\": \"shortcode\",\n      \"identifier\": \"MailchimpForm\",\n      \"attributes\": { \"id\": \"chfk2\" }\n    }\n  ]\n};\n\nvar tree = unified()\n  .use(parse)\n  // Plugin inserted below, with custom options for start/end blocks.\n  .use(shortcodes, {startBlock: \"{{\u003e\", endBlock: \"\u003c}}\"})\n  .stringify(ast);\n\nconsole.log(tree);\n```\n\nRunning `node example2` yields:\n\n```markdown\nExample paragraph\\n\\n{{\u003e MailchimpForm id=\"chfk2\" \u003c}}\n```\n\nSay `example3.js` looks as follows:\n\n```javascript\nvar unified = require('unified');\nvar parse = require('remark-parse');\nvar shortcodes = require('remark-shortcodes');\n\nvar markdown = 'Example paragraph {{\u003e MailchimpForm id=\"chfk2\" \u003c}}'\n\nvar tree = unified()\n  .use(parse)\n  // Plugin inserted below, with custom options for start/end blocks.\n  .use(shortcodes, {startBlock: \"{{\u003e\", endBlock: \"\u003c}}\", inlineMode: true})\n  // Turn off position output for legibility below.\n  .data('settings', {position: false})\n  .parse(markdown);\n\nconsole.dir(tree, {depth: null});\n```\n\nRunning `node example3` yields:\n\n```json\n{\n  \"type\": \"root\",\n  \"children\": [\n    {\n      \"type\": \"paragraph\",\n      \"children\": [\n        {\n          \"type\": \"text\",\n          \"value\": \"Example paragraph \"\n        },\n        {\n          \"type\": \"shortcode\",\n          \"identifier\": \"MailchimpForm\",\n          \"attributes\": { \"id\": \"chfk2\" }\n        }\n      ]\n    }\n  ]\n}\n```\n\n## API\n\n### `remark.use(shortcodes, {options})`\n\nWhere options support the keys:\n\n- `startBlock`: the start block to look for. Default: `[[`.\n- `endBlock`: the end block to look for. Default: `]]`.\n- `inlineMode`: shortcodes will be parsed inline rather than in block mode. Default: `false`.\n\nNB: Be careful when using custom start/end blocks, your choices\nmay clash with other markdown syntax and/or other remark plugins.\n\n## Testing\n\nTo run the tests, run:\n\n    npm run test-code\n\nTo run build, tests \u0026 coverage, run:\n\n    npm run test\n\nCI is set up on push via a Github Action, see [workflows/nodejs.yml](https://github.com/djm/remark-shortcodes/blob/master/.github/workflows/nodejs.yml).\n\n## Releasing\n\nPrepare the commits:\n\n- Bump all version numbers.\n- Tag the commit: `git tag -a v0.1.x -m v0.1.x`\n- Push tag to Github: `git push --tags`\n\nPublish to npm:\n\n- Ensure tag is checked-out: `git checkout tags/v0.1.x`\n- Login to NPM via the CLI: `npm login`\n- Publish the package: `npm publish`\n\n## License\n\n[MIT](LICENSE) © [Darian Moody](http://djm.org.uk)\n\nWith thanks to [woorm][woorm] et. al for [**remark**][remark].\n\n\u003c!-- Links --\u003e\n\n[npm-package-badge]: https://img.shields.io/npm/v/remark-shortcodes.svg\n\n[npm-package]: https://www.npmjs.org/package/remark-shortcodes\n\n[codecov-badge]: https://img.shields.io/codecov/c/github/djm/remark-shortcodes.svg\n\n[codecov]: https://codecov.io/github/djm/remark-shortcodes\n\n[wordpress-shortcodes]: https://codex.wordpress.org/shortcode\n\n[hugo-shortcodes]: https://gohugo.io/content-management/shortcodes/\n\n[gatsby-remark-shortcodes]: https://gitub.com/djm/gatsby-remark-shortcodes\n\n[npm]: https://docs.npmjs.com/cli/install\n\n[node]: https://github.com/syntax-tree/unist#node\n\n[remark]: https://github.com/wooorm/remark\n\n[woorm]: https://github.com/wooorm\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjm%2Fremark-shortcodes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjm%2Fremark-shortcodes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjm%2Fremark-shortcodes/lists"}