{"id":20603353,"url":"https://github.com/metalsmith/slots","last_synced_at":"2025-03-06T16:38:31.820Z","repository":{"id":221261064,"uuid":"750029449","full_name":"metalsmith/slots","owner":"metalsmith","description":"A Metalsmith plugin to divide file contents in slots, associate metadata with them and process them separately","archived":false,"fork":false,"pushed_at":"2024-02-07T01:11:34.000Z","size":23,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-17T02:11:32.522Z","etag":null,"topics":["frontmatter","metalsmith","metalsmith-plugin","sections","slots"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metalsmith.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-01-29T21:15:03.000Z","updated_at":"2024-02-07T01:05:29.000Z","dependencies_parsed_at":"2024-02-07T02:24:06.122Z","dependency_job_id":"4c74cb4e-3606-48b4-9cf7-f3c77958afa1","html_url":"https://github.com/metalsmith/slots","commit_stats":null,"previous_names":["metalsmith/slots"],"tags_count":0,"template":false,"template_full_name":"metalsmith/core-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fslots","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fslots/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fslots/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fslots/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metalsmith","download_url":"https://codeload.github.com/metalsmith/slots/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242248921,"owners_count":20096760,"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":["frontmatter","metalsmith","metalsmith-plugin","sections","slots"],"created_at":"2024-11-16T09:17:02.352Z","updated_at":"2025-03-06T16:38:31.779Z","avatar_url":"https://github.com/metalsmith.png","language":"JavaScript","readme":"# @metalsmith/slots\n\nA Metalsmith plugin to divide file contents into slots, associate metadata with them and process them separately\n\n[![metalsmith: core plugin][metalsmith-badge]][metalsmith-url]\n[![npm: version][npm-badge]][npm-url]\n[![ci: build][ci-badge]][ci-url]\n[![code coverage][codecov-badge]][codecov-url]\n[![license: MIT][license-badge]][license-url]\n\n## Installation\n\nNPM:\n\n```\nnpm install @metalsmith/slots\n```\n\nYarn:\n\n```\nyarn add @metalsmith/slots\n```\n\n## Usage\n\nPass `@metalsmith/slots` to `metalsmith.use`:\n\n```js\nimport slots from '@metalsmith/slots'\n\nmetalsmith.use(slots()) // defaults\nmetalsmith.use(\n  slots({\n    // explicit defaults\n    pattern: '**/*.{md,html}'\n  })\n)\n```\n\nNow you can divide your file in parameterized logical content sections or _slots_, with their own front-matter blocks.\nJust define the `slot` field for each. You can associate any metadata with the slots just like file front-matter.\n\n```yaml\n---\nlayout: default.njk\ntitle: This becomes file.title\n---\nThis becomes file.contents\n--- # first slot (becomes file.slots.author)\nslot: author\nname: John Doe\ntopics: [sports, finance]\n---\nThis becomes file.slots.author.contents\n--- # second slot (becomes file.slots.ads)\nslot: ads\nurl: https://someadprovider.com/?id=abcde1234\n---\n\u003c!-- end of file --\u003e\n```\n\n@metalsmith/slots then parses the file, removing the slots content from the main `file.contents` field and adding them to `file.slots`:\n\n```js\nconst file = {\n  layout: 'default.njk',\n  title: 'This becomes file.title',\n  contents: Buffer.from('This becomes file.contents'),\n  slots: {\n    author: {\n      slot: 'author',\n      name: 'John Doe',\n      contents: 'This becomes file.slots.author.contents',\n      topics: ['sports', 'finance']\n    },\n    ads: {\n      slot: 'ads',\n      contents: '\u003c!-- end of file --\u003e',\n      url: 'https://someadprovider.com/?id=abcde1234'\n    }\n  }\n}\n```\n\nIf the file already has an existing `slots` property holding an object, the slots will be shallowly merged in with `Object.assign`.\nIf the file already has an existing property with another type, it will be overwritten and log a debug warning.\n\nThere is one limitation: you cannot \\*interrupt\\* the main content with a slot and then continue it. Because front-matter is parsed without an explicit \"end\" boundary, slots must always be defined at the end of the file.\n\n### Defining default slots\n\nYou can define a _slots_ property in [metalsmith.metadata()](https://metalsmith.io/api/#Metalsmith+metadata):\n\n```js\nmetalsmith.metadata({\n  slots: {\n    author: {\n      slot: 'author',\n      name: 'Anonymous',\n      contents: 'This author preferred we not publish their identity'\n    }\n  }\n})\n```\n\nThis property can then be used by plugins like [@metalsmith/layouts](https://github.com/metalsmith/layouts) that merge file metadata into global metadata as rendering context.\n\nIf you rather really _set_ the defaults to the files so other plugins can access it, you can use [@metalsmith/default-values](https://github.com/metalsmith/default-values)\n\n### Rendering slots in a layout\n\nWith the previous examples, [@metalsmith/layouts](https://github.com/metalsmith/layouts) can render slots in a layout, using slots defined inline in a file, or fall back to metalsmith.metadata:\n\n```html\n\u003chtml lang=\"en\"\u003e\n  \u003chead\u003e\n    \u003cmeta charset=\"UTF-8\" /\u003e\n    \u003ctitle\u003e{{ title }}\u003c/title\u003e\n  \u003c/head\u003e\n  \u003cbody\u003e\n    \u003carticle\u003e\n      \u003caside\u003e\n        \u003ciframe src=\"{{ slots.ads.url }}\"\u003e\u003c/iframe\u003e\n      \u003c/aside\u003e\n      {{ contents | safe }}\n      \u003cfooter\u003e\n        \u003ch3\u003eBy {{ slots.author.name }}\u003c/h3\u003e\n        Writes about {{ slots.author.topics | join(', ') }}\n        \u003cp\u003e{{ slots.author.contents }}\u003c/p\u003e\n      \u003c/footer\u003e\n    \u003c/article\u003e\n  \u003c/body\u003e\n\u003c/html\u003e\n```\n\nNote that you can also use `{{ slots.slotname }}` as an alias for `{{ slots.slotname.contents }}` in templating languages that `toString()` the values they output.\n\nIt is not (yet) possible to render slots into their own layouts by defining a slot `layout` field.\n\n### Rendering markdown in a slot\n\nIt is easy to render markdown in slots with [@metalsmith/markdown](https://github.com/metalsmith/markdown)'s `keys` and `wildcard` options to target slot contents of all files:\n\n```js\nmetalsmith.use(\n  markdown({\n    wildcard: true,\n    keys: ['slots.*.contents']\n  })\n)\n```\n\n### Rendering slots in file.contents\n\n[@metalsmith/in-place](https://github.com/metalsmith/in-place) can be used to render slots inside the file.contents.\n\n`index.md`\n\n```yaml\n---\nlayout: default.njk\ntitle: This becomes file.title\n---\n\u003ch1\u003e{{ title }}\u003c/h1\u003e\nThis becomes file.contents\n\nBy {{ slots.author.name }}.\nWrites mostly about {{ slots.author.topics | join(', ') }}\n\u003chr\u003e{{ slots.author.contents | safe }}\n---\nslot: author\nname: John Doe\ntopics: [sports, finance]\n---\nThis becomes file.slots.author.contents.\n```\n\n### Combining plugins\n\nAn example of using all of @metalsmith layouts, in-place, markdown, default-values and slots in a common order in a metalsmith build:\n\n```js\nmetalsmith\n  // default slots for all files processed with @metalsmith/layouts or in-place\n  .metadata({\n    slots: {\n      author: {\n        slot: 'author',\n        name: 'Anonymous',\n        contents: 'This author preferred we not publish their identity'\n      }\n    }\n  })\n  // default slots by file pattern, eg no author for homepage\n  .use(\n    defaultValues([\n      {\n        pattern: 'home.md',\n        defaults: { slots: (file) =\u003e ({ ...(file.slots || {}), author: false }) }\n      }\n    ])\n  )\n  .use(slots({ pattern: '**/*.md' }))\n  // render markdown inside slots\n  .use(markdown({ wildcard: true, keys: ['slots.*.contents'] }))\n  // render slots inside file.contents\n  .use(inPlace({ pattern: '**/*.html', transform: 'nunjucks' }))\n  // render slots inside a file layout\n  .use(layouts({ pattern: '**/*.html' }))\n```\n\n### Debug\n\nTo enable debug logs, set the `DEBUG` environment variable to `@metalsmith/slots*`:\n\n```js\nmetalsmith.env('DEBUG', '@metalsmith/slots*')\n```\n\nAlternatively you can set `DEBUG` to `@metalsmith/*` to debug all Metalsmith core plugins.\n\n### CLI usage\n\nTo use this plugin with the Metalsmith CLI, add `@metalsmith/slots` to the `plugins` key in your `metalsmith.json` file:\n\n```json\n{\n  \"plugins\": [\n    {\n      \"@metalsmith/slots\": {}\n    }\n  ]\n}\n```\n\n## License\n\n[MIT](LICENSE)\n\n[npm-badge]: https://img.shields.io/npm/v/@metalsmith/slots.svg\n[npm-url]: https://www.npmjs.com/package/@metalsmith/slots\n[ci-badge]: https://github.com/metalsmith/slots/actions/workflows/test.yml/badge.svg\n[ci-url]: https://github.com/metalsmith/slots/actions/workflows/test.yml\n[metalsmith-badge]: https://img.shields.io/badge/metalsmith-core_plugin-green.svg?longCache=true\n[metalsmith-url]: https://metalsmith.io\n[codecov-badge]: https://img.shields.io/coveralls/github/metalsmith/slots\n[codecov-url]: https://coveralls.io/github/metalsmith/slots\n[license-badge]: https://img.shields.io/github/license/metalsmith/slots\n[license-url]: LICENSE\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fslots","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetalsmith%2Fslots","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fslots/lists"}