{"id":20603345,"url":"https://github.com/metalsmith/refs","last_synced_at":"2026-02-15T22:06:23.358Z","repository":{"id":222215687,"uuid":"756285226","full_name":"metalsmith/refs","owner":"metalsmith","description":"A metalsmith plugin to refer to other files and global metadata from a file's refs property","archived":false,"fork":false,"pushed_at":"2026-02-08T23:51:03.000Z","size":1201,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-09T05:05:38.149Z","etag":null,"topics":["metadata","metalsmith","metalsmith-plugin","reference"],"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,"publiccode":null,"codemeta":null}},"created_at":"2024-02-12T11:10:02.000Z","updated_at":"2026-02-08T23:51:06.000Z","dependencies_parsed_at":"2024-02-16T00:32:10.410Z","dependency_job_id":"c7516705-bcab-41ea-8e12-c64f3ddcf579","html_url":"https://github.com/metalsmith/refs","commit_stats":{"total_commits":18,"total_committers":1,"mean_commits":18.0,"dds":0.0,"last_synced_commit":"24838df040f9d8ab4a52d5bbc7c528a69ad2d799"},"previous_names":["metalsmith/refs"],"tags_count":2,"template":false,"template_full_name":"metalsmith/core-plugin","purl":"pkg:github/metalsmith/refs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Frefs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Frefs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Frefs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Frefs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metalsmith","download_url":"https://codeload.github.com/metalsmith/refs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Frefs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29490360,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T19:29:10.908Z","status":"ssl_error","status_checked_at":"2026-02-15T19:29:10.419Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["metadata","metalsmith","metalsmith-plugin","reference"],"created_at":"2024-11-16T09:16:58.108Z","updated_at":"2026-02-15T22:06:23.345Z","avatar_url":"https://github.com/metalsmith.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @metalsmith/refs\n\nA metalsmith plugin to easily refer to other files and global metadata from `file.refs`\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: LGPL][license-badge]][license-url]\n\n## Features\n\n- Gives your files a default, but customizable _identity_ matching its relative file path\n- Substitutes a file's `refs` keypaths with their target file- or metadata values\n- Allows tracing a file's manipulations via its `id` property\n- Batch assign references with [@metalsmith/default-values](https://github.com/metalsmith/default-values)\n\n## Installation\n\nNPM:\n\n```\nnpm install @metalsmith/refs\n```\n\nYarn:\n\n```\nyarn add @metalsmith/refs\n```\n\n## Usage\n\nPass `@metalsmith/refs` to `metalsmith.use` :\n\n```js\nimport refs from '@metalsmith/refs'\nimport layouts from '@metalsmith/layouts'\n\nmetalsmith.use(refs()) // defaults\nmetalsmith.use(\n  refs({\n    // explicit defaults\n    pattern: '**'\n  })\n)\n```\n\nNow you can, say, reference child documentation pages in the index `src/docs/index.html`:\n\n```yaml\n---\nid: docs_index\nrefs:\n  # relative refs will be resolved vs the current file\n  getting_started: file:./getting-started/index.html\n  # absolute refs will be resolved vs metalsmith.source()\n  usage_guide: file:/docs/usage-guide/index.html\n---\n```\n\nRefs are defined in a `protocol:path` format. As a shortcut, not specifying the `protocol:` part will default to `file:`.\n\nWhen @metalsmith/refs runs, it will substitute the refs with the actual files:\n\n```js\n{\n  'docs/index.html': {\n    id: 'docs_index',\n    refs: {\n      getting_started: {\n        id: 'docs/getting-started/index.html',\n        contents: Buffer.from('...'),\n        stats: {...}\n      },\n      usage_guide: {\n        id: 'docs/usage-guide/index.html',\n        contents: Buffer.from('...'),\n        stats: {...}\n      }\n    }\n  }\n}\n```\n\nThe file references are [_Proxy objects_](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) of the targets they refer to, i.e. they will be in sync when other plugins alter them later. To avoid circular references, you cannot access a ref's own refs.\n\nAs the example above shows, @metalsmith/refs will also add an `id` property to each processed file, unless you define an [explicit id](#custom-ids). By default the `id` is the file's path relative to metalsmith.source(), and with backslashes converted to forward slashes for cross-platform compatibility.\n\n### Plugin order\n\nIt is advised to use this plugin at the start of your build chain. Why? If you used plugins like [@metalsmith/permalinks](https://github.com/metalsmith/permalinks) that change the file's path before this plugin, the `id` property will not match the source path of the file.\n\nUsing @metalsmith/refs at the start of your plugin chain gives you an easy way to _trace_ file transforms by other plugins.\n\n### Custom ids\n\nYou can define an id property before @metalsmith/refs runs, and it will not be overwritten. In the example above, the getting-started and usage-guide pages could refer to the index with the `id:` protocol:\n\n```yaml\n---\nrefs:\n  docs_home: id:docs_index\n---\n```\n\nThis is useful if you wish to decouple a file's identity from its path on disk and to avoid having to commit a lot of small changes when/if you plan to reorganize source files.\n\n### Reference global metadata\n\nMetalsmith.metadata() keys can be referenced with the `metadata:` protocol, e.g.:\n\n`docs/index.html`\n\n```yaml\n---\nrefs:\n  navigation: metadata:navigation\n  articles: metadata:collections.articles\n---\n```\n\nAs the example demonstrates `dot.delimited.keypaths` are also supported.\n\nReferencing the entire `metalsmith.metadata()` object is not possible. Plugins like [@metalsmith/in-place](https://github.com/metalsmith/in-place) or [@metalsmith/layouts](https://github.com/metalsmith/layouts) already allow access to the global metadata in their render contexts.\n\n### Batch references by filepath\n\nUse [@metalsmith/default-values](https://github.com/metalsmith/default-values) before @metalsmith/refs to automatically assign refs by glob patterns:\n\n```js\nmetalsmith\n  .use(\n    defaultValues([\n      {\n        pattern: 'docs/*/*.html',\n        defaults: {\n          refs: {\n            docs_index: 'file:./docs/index.html',\n            globalLinks: 'metadata:globalLinks'\n          }\n        }\n      }\n    ])\n  )\n  .use(refs())\n```\n\n### Debug\n\nTo enable debug logs, set the `DEBUG` environment variable to `@metalsmith/refs*`:\n\n```js\nmetalsmith.env('DEBUG', '@metalsmith/refs*')\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/refs` to the `plugins` key in your `metalsmith.json` file:\n\n```json\n{\n  \"plugins\": [\n    {\n      \"@metalsmith/refs\": {}\n    }\n  ]\n}\n```\n\n## License\n\n[LGPL-3.0](LICENSE)\n\n[npm-badge]: https://img.shields.io/npm/v/@metalsmith/refs.svg\n[npm-url]: https://www.npmjs.com/package/@metalsmith/refs\n[ci-badge]: https://github.com/metalsmith/refs/actions/workflows/test.yml/badge.svg\n[ci-url]: https://github.com/metalsmith/refs/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/refs\n[codecov-url]: https://coveralls.io/github/metalsmith/refs\n[license-badge]: https://img.shields.io/github/license/metalsmith/refs\n[license-url]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Frefs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetalsmith%2Frefs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Frefs/lists"}