{"id":14155612,"url":"https://github.com/metalsmith/markdown","last_synced_at":"2025-04-06T01:07:42.484Z","repository":{"id":13839871,"uuid":"16536856","full_name":"metalsmith/markdown","owner":"metalsmith","description":"A metalsmith plugin to render markdown files to HTML.","archived":false,"fork":false,"pushed_at":"2024-03-04T00:35:54.000Z","size":849,"stargazers_count":62,"open_issues_count":6,"forks_count":65,"subscribers_count":37,"default_branch":"main","last_synced_at":"2025-04-02T06:39:43.587Z","etag":null,"topics":["markdown","metalsmith","metalsmith-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/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":"2014-02-05T06:13:17.000Z","updated_at":"2025-02-09T00:46:59.000Z","dependencies_parsed_at":"2024-01-19T09:01:29.740Z","dependency_job_id":"e1859543-eebf-4924-b757-b47f0e888aa3","html_url":"https://github.com/metalsmith/markdown","commit_stats":{"total_commits":94,"total_committers":16,"mean_commits":5.875,"dds":0.4148936170212766,"last_synced_commit":"61976dc7495f409dbb894b773b60d69e4c9b28d6"},"previous_names":["segmentio/metalsmith-markdown"],"tags_count":18,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fmarkdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fmarkdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fmarkdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metalsmith%2Fmarkdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metalsmith","download_url":"https://codeload.github.com/metalsmith/markdown/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419860,"owners_count":20936012,"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":["markdown","metalsmith","metalsmith-plugin"],"created_at":"2024-08-17T08:04:25.613Z","updated_at":"2025-04-06T01:07:42.467Z","avatar_url":"https://github.com/metalsmith.png","language":"JavaScript","funding_links":[],"categories":["markdown"],"sub_categories":[],"readme":"# @metalsmith/markdown\n\nA Metalsmith plugin to render markdown files to HTML, using [Marked](https://github.com/markedjs/marked) (by default).\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## Features\n\n- Compiles `.md` and `.markdown` files in `metalsmith.source()` to HTML.\n- Enables rendering file or metalsmith metadata keys to HTML through the [keys option](#rendering-metadata)\n- Define a dictionary of markdown globalRefs (for links, images) available to all render targets\n- Supports using the markdown library of your choice through the [render option](#using-another-markdown-library)\n\n## Installation\n\nNPM:\n\n```bash\nnpm install @metalsmith/markdown\n```\n\nYarn:\n\n```bash\nyarn add @metalsmith/markdown\n```\n\n## Usage\n\n`@metalsmith/markdown` is powered by [Marked](https://github.com/markedjs/marked) (by default), and you can pass any of the [Marked options](https://marked.js.org/using_advanced#options) to it, including the ['pro' options](https://marked.js.org/using_pro#extensions): `renderer`, `tokenizer`, `walkTokens` and `extensions`.\n\n```js\nimport markdown from '@metalsmith/markdown'\nimport hljs from 'highlight.js'\n\n// use defaults\nmetalsmith.use(markdown())\n\n// use explicit defaults\nmetalsmith.use({\n  wildcard: false,\n  keys: [],\n  engineOptions: {}\n})\n\n// custom\nmetalsmith.use(\n  markdown({\n    engineOptions: {\n      highlight: function (code) {\n        return hljs.highlightAuto(code).value\n      },\n      pedantic: false,\n      gfm: true,\n      tables: true,\n      breaks: false,\n      sanitize: false,\n      smartLists: true,\n      smartypants: false,\n      xhtml: false\n    }\n  })\n)\n```\n\n`@metalsmith/markdown` provides the following options:\n\n- `keys`: Key names of file metadata to render to HTML in addition to its `contents` - can be nested key paths\n- `wildcard` _(default: `false`)_ - Expand `*` wildcards in `keys` option keypaths\n- `globalRefs` - An object of `{ refname: 'link' }` pairs that will be available for all markdown files and keys, or a `metalsmith.metadata()` keypath containing such object\n- `render` - Specify a custom render function with the signature `(source, engineOptions, context) =\u003e string`. `context` is an object with the signature `{ path:string, key:string }` where the `path` key contains the current file path, and `key` contains the target metadata key.\n- `engineOptions` Options to pass to the markdown engine (default [marked](https://github.com/markedjs/marked))\n\n### Rendering metadata\n\nYou can render markdown to HTML in file or metalsmith metadata keys by specifying the `keys` option.  \nThe `keys` option also supports dot-delimited key-paths. You can also use [globalRefs within them](#defining-a-dictionary-of-markdown-globalrefs)\n\n```js\nmetalsmith\n  .metadata({\n    from_metalsmith_metadata: 'I _shall_ become **markdown** and can even use a [globalref][globalref_link]',\n    markdownRefs: {\n      globalref_link: 'https://johndoe.com'\n    }\n  })\n  .use(\n    markdown({\n      keys: {\n        files: ['html_desc', 'nested.data'],\n        global: ['from_metalsmith_metadata']\n      },\n      globalRefs: 'markdownRefs'\n    })\n  )\n```\n\nYou can even render all keys at a certain path by setting the `wildcard` option and using a globstar `*` in the keypaths.  \nThis is especially useful for arrays like the `faq` below:\n\n```js\nmetalsmith.use(\n  markdown({\n    wildcard: true,\n    keys: ['html_desc', 'nested.data', 'faq.*.*']\n  })\n)\n```\n\nA file `page.md` with front-matter:\n\n```md\n---\nhtml_desc: A **markdown-enabled** _description_\nnested:\n  data: '#metalsmith'\nfaq:\n  - q: '**Question1?**'\n    a: _answer1_\n  - q: '**Question2?**'\n    a: _answer2_\n---\n```\n\nwould be transformed into:\n\n```json\n{\n  \"html_desc\": \"A \u003cstrong\u003emarkdown-enabled\u003c/strong\u003e \u003cem\u003edescription\u003c/em\u003e\\n\",\n  \"nested\": {\n    \"data\": \"\u003ch1 id=\\\"metalsmith\\\"\u003emetalsmith\u003c/h1\u003e\\n\"\n  },\n  \"faq\": [\n    { \"q\": \"\u003cp\u003e\u003cstrong\u003eQuestion1?\u003c/strong\u003e\u003c/p\u003e\\n\", \"a\": \"\u003cp\u003e\u003cem\u003eanswer1\u003c/em\u003e\u003c/p\u003e\\n\" },\n    { \"q\": \"\u003cp\u003e\u003cstrong\u003eQuestion2?\u003c/strong\u003e\u003c/p\u003e\\n\", \"a\": \"\u003cp\u003e\u003cem\u003eanswer2\u003c/em\u003e\u003c/p\u003e\\n\" }\n  ]\n}\n```\n\n**Notes about the wildcard**\n\n- It acts like the single bash globstar. If you specify `*` this would only match the properties at the first level of the metadata.\n- If a wildcard keypath matches a key whose value is not a string, it will be ignored.\n- It is set to `false` by default because it can incur some overhead if it is applied too broadly.\n\n### Defining a dictionary of markdown globalRefs\n\nMarkdown allows users to define links in [reference style](https://www.markdownguide.org/basic-syntax/#reference-style-links) (`[]:`).  \nIn a Metalsmith build it may be especially desirable to be able to refer to some links globally. The `globalRefs` options allows this:\n\n```js\nmetalsmith.use(\n  markdown({\n    globalRefs: {\n      twitter_link: 'https://twitter.com/johndoe',\n      github_link: 'https://github.com/johndoe',\n      photo: '/assets/img/me.png'\n    }\n  })\n)\n```\n\nNow _contents of any file or metadata key_ processed by @metalsmith/markdown will be able to refer to these links as `[My Twitter][twitter_link]` or `![Me][photo]`. You can also store the globalRefs object of the previous example in a `metalsmith.metadata()` key and pass its keypath as `globalRefs` option instead.\n\nThis enables a flow where you can load the refs into global metadata from a source file with [@metalsmith/metadata](https://github.com/metalsmith/metadata), and use them both in markdown and templating plugins like [@metalsmith/layouts](https://github.com/metalsmith/layouts):\n\n```js\nmetalsith\n  .metadata({\n    global: {\n      links: {\n        twitter: 'https://twitter.com/johndoe',\n        github: 'https://github.com/johndoe'\n      }\n    }\n  })\n  // eg in a markdown file: [My Twitter profile][twitter]\n  .use(markdown({ globalRefs: 'global.links' }))\n  // eg in a handlebars layout: {{ global.links.twitter }}\n  .use(layouts({ pattern: '**/*.html' }))\n```\n\n### Custom markdown rendering\n\nYou can use a custom renderer by using `marked.Renderer()`\n\n```js\nimport markdown from '@metalsmith/markdown'\nimport { marked } from 'marked'\nconst markdownRenderer = new marked.Renderer()\n\nmarkdownRenderer.image = function (href, title, text) {\n  return `\n  \u003cfigure\u003e\n    \u003cimg src=\"${href}\" alt=\"${title}\" title=\"${title}\" /\u003e\n    \u003cfigcaption\u003e\n      \u003cp\u003e${text}\u003c/p\u003e\n    \u003c/figcaption\u003e\n  \u003c/figure\u003e`\n}\n\nmetalsmith.use(\n  markdown({\n    engineOptions: {\n      renderer: markdownRenderer,\n      pedantic: false,\n      gfm: true,\n      tables: true,\n      breaks: false,\n      sanitize: false,\n      smartLists: true,\n      smartypants: false,\n      xhtml: false\n    }\n  })\n)\n```\n\n### Using another markdown library\n\nIf you don't want to use marked, you can use another markdown rendering library through the `render` option. For example, this is how you could use [markdown-it](https://github.com/markdown-it/markdown-it) instead:\n\n```js\nimport MarkdownIt from 'markdown-it'\n\nlet markdownIt\nmetalsmith.use(markdown({\n  render(source, opts, context) {\n    if (!markdownIt) markdownIt = new MarkdownIt(opts)\n    if (context.key == 'contents') return mdIt.render(source)\n    return markdownIt.renderInline(source)\n  },\n  // specify markdownIt options here\n  engineOptions: { ... }\n}))\n```\n\n### Debug\n\nTo enable debug logs, set the `DEBUG` environment variable to `@metalsmith/markdown*`:\n\n```\nmetalsmith.env('DEBUG', '@metalsmith/markdown*')\n```\n\n### CLI Usage\n\nAdd `@metalsmith/markdown` key to your `metalsmith.json` plugins key\n\n```json\n{\n  \"plugins\": {\n    \"@metalsmith/markdown\": {\n      \"engineOptions\": {\n        \"pedantic\": false,\n        \"gfm\": true,\n        \"tables\": true,\n        \"breaks\": false,\n        \"sanitize\": false,\n        \"smartLists\": true,\n        \"smartypants\": false,\n        \"xhtml\": false\n      }\n    }\n  }\n}\n```\n\n## License\n\n[MIT](LICENSE)\n\n[npm-badge]: https://img.shields.io/npm/v/@metalsmith/markdown.svg\n[npm-url]: https://www.npmjs.com/package/@metalsmith/markdown\n[ci-badge]: https://github.com/metalsmith/markdown/actions/workflows/test.yml/badge.svg\n[ci-url]: https://github.com/metalsmith/markdown/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/markdown\n[codecov-url]: https://coveralls.io/github/metalsmith/markdown\n[license-badge]: https://img.shields.io/github/license/metalsmith/markdown\n[license-url]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fmarkdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetalsmith%2Fmarkdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetalsmith%2Fmarkdown/lists"}