{"id":15048744,"url":"https://github.com/hexojs/hexo-renderer-markdown-it","last_synced_at":"2025-05-16T12:01:46.096Z","repository":{"id":25629091,"uuid":"29064373","full_name":"hexojs/hexo-renderer-markdown-it","owner":"hexojs","description":"Markdown-it is a Markdown parser, done right. A faster and CommonMark compliant alternative for Hexo.","archived":false,"fork":false,"pushed_at":"2024-02-01T06:35:10.000Z","size":188,"stargazers_count":358,"open_issues_count":17,"forks_count":58,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-15T11:09:45.202Z","etag":null,"topics":["hexo","hexo-plugin","javascript"],"latest_commit_sha":null,"homepage":null,"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/hexojs.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-01-10T17:12:46.000Z","updated_at":"2025-03-15T12:16:20.000Z","dependencies_parsed_at":"2022-08-25T02:20:51.030Z","dependency_job_id":"b74a3b20-b990-4f19-8e43-aa285c3e5518","html_url":"https://github.com/hexojs/hexo-renderer-markdown-it","commit_stats":{"total_commits":201,"total_committers":19,"mean_commits":"10.578947368421053","dds":0.5771144278606966,"last_synced_commit":"0c5034e87fff9ad9de1b4663b99a08b8ba434653"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexojs%2Fhexo-renderer-markdown-it","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexojs%2Fhexo-renderer-markdown-it/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexojs%2Fhexo-renderer-markdown-it/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hexojs%2Fhexo-renderer-markdown-it/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hexojs","download_url":"https://codeload.github.com/hexojs/hexo-renderer-markdown-it/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254527071,"owners_count":22085917,"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":["hexo","hexo-plugin","javascript"],"created_at":"2024-09-24T21:15:55.485Z","updated_at":"2025-05-16T12:01:46.071Z","avatar_url":"https://github.com/hexojs.png","language":"JavaScript","readme":"# hexo-renderer-markdown-it\n\n[![Build Status](https://github.com/hexojs/hexo-renderer-markdown-it/workflows/Tester/badge.svg)](https://github.com/hexojs/hexo-renderer-markdown-it/actions?query=workflow%3ATester)\n[![npm version](https://badge.fury.io/js/hexo-renderer-markdown-it.svg)](https://www.npmjs.com/package/hexo-renderer-markdown-it)\n[![Coverage Status](https://coveralls.io/repos/github/hexojs/hexo-renderer-markdown-it/badge.svg?branch=master)](https://coveralls.io/github/hexojs/hexo-renderer-markdown-it?branch=master)\n\nThis renderer plugin uses [Markdown-it] as a render engine on [Hexo]. Adds support for [Markdown] and [CommonMark].\n\n## Main Features\n\n- Support for [Markdown], [GFM] and [CommonMark]\n- Extensive configuration\n- Faster than the default renderer | `hexo-renderer-marked`\n- Safe ID for headings\n- Anchors for headings with ID\n- Footnotes\n- `\u003csub\u003e` H\u003csub\u003e2\u003c/sub\u003eO\n- `\u003csup\u003e` x\u003csup\u003e2\u003c/sup\u003e\n- `\u003cins\u003e` \u003cins\u003eInserted\u003c/ins\u003e\n\n## Installation\n\n**Warning:** make sure you're inside the main hexo directory before starting this guide.\n\nA default Hexo installation will include a markdown renderer plugin which uses `marked`, so you will have to remove it if you want to use `hexo-renderer-markdown-it`.\n\n``` sh\n$ npm un hexo-renderer-marked --save\n```\n\nIf you have already removed the default renderer, and others you might of added, you can now safely install `hexo-renderer-markdown-it`\n\n``` sh\n$ npm i hexo-renderer-markdown-it --save\n```\n\n## Options\n\n``` yml\nmarkdown:\n  preset: 'default'\n  render:\n    html: true\n    xhtmlOut: false\n    langPrefix: 'language-'\n    breaks: true\n    linkify: true\n    typographer: true\n    quotes: '“”‘’'\n  enable_rules:\n  disable_rules:\n  plugins:\n  anchors:\n    level: 2\n    collisionSuffix: ''\n    permalink: false\n    permalinkClass: 'header-anchor'\n    permalinkSide: 'left'\n    permalinkSymbol: '¶'\n    case: 0\n    separator: '-'\n  images:\n    lazyload: false\n    prepend_root: false\n    post_asset: false\n  inline: false  # https://markdown-it.github.io/markdown-it/#MarkdownIt.renderInline\n```\n\nSee below for more details.\n\n## Advanced Configuration\n\n### [Preset](https://markdown-it.github.io/markdown-it/#MarkdownIt.new) options\n\n``` yml\nmarkdown:\n  preset: 'default'\n```\n\n- **\"commonmark\"** - configures parser to strict [CommonMark](https://commonmark.org/) mode.\n- **\"default\"** - similar to [GFM](https://github.github.com/gfm/), used when no preset name given. Enables all available rules, but still without html, typographer \u0026 autolinker.\n- **\"zero\"** - all rules disabled. Useful to quickly setup your config via `.enable()`. For example, when you need only `bold` and `italic` markup and nothing else.\n\nNote that the [default](https://github.com/hexojs/hexo-renderer-markdown-it#options) render and anchor options override some options in the preset. If you prefer to have the preset only:\n\n``` yml\nmarkdown:\n  preset: 'default'\n  render:\n  anchors:\n```\n\n### Render options\n\n#### html\n\nThe `html` setting defines whether or not HTML content inside the document should be escaped or passed to the final result.\n\n``` yaml\nhtml: true # Doesn't escape HTML content\n    ## OR\nhtml: false # Escapes HTML content so the tags will appear as text.\n```\n\n#### xhtmlOut\n\nThe `xhtmlOut` setting defines whether the parser will export fully XHTML compatible tags. This only needs to be `true` for complete [CommonMark] support.\n\n``` yaml\nxhtmlOut: true # Parser produces fully XHTML compliant code.\n               # Ex: A line breaks will be \u003cbr /\u003e\n    ## OR\nxhtmlOut: false # Parser will not produce XHTML compliant code.\n                # Ex: A line break will be \u003cbr\u003e\n```\n\n#### breaks\n\nMakes line breaks in the source file will be parsed into `\u003cbr\u003e` tags. So every time you press the `Enter` key you will create a line break, which is not the default Markdown, CommonMark, or GFM behaviour.\n\n``` yaml\nbreaks: true # Parser produces `\u003cbr\u003e` tags every time there is a line break in the source document.\n    ## OR\nbreaks: false # Parser will ignore line breaks in the source document.\n              #Default double line break creates paragraph is still supported\n```\n\n#### langPrefix\n\nAdd a prefix to the class name of code blocks (when a language is specified).\n\n``` yaml\nlangPrefix: 'language-' # default\n```\n\n_This option only applies when both Hexo's built-in highlighters are [**disabled**](https://hexo.io/docs/syntax-highlight#Disabled)._\n\n**Example:**\n\n``` yml\nlangPrefix: 'lang-'\n```\n\nSource:\n````\n``` js\nexample\n```\n````\n\nHTML:\n\n```html\n\u003cpre\u003e\n\u003ccode class=\"lang-js\"\u003eexample\u003c/code\u003e\n\u003c/pre\u003e\n```\n\n#### linkify\n\nThe parser has the ability to inline links pasted directly into the text. If you write a piece of text that looks like a link it will be rendered as `\u003ca src=\"http://example.com\"\u003ehttp://example.com\u003c/a\u003e`.\n\n``` yaml\nlinkify: true # Returns text links as proper links inlined with the paragraph.\n    ## OR\nlinkify: false # Returns text links as text.\n```\n\n#### typographer\n\nThis is enables the substitution for common typography elements like \u0026copy;, curly quotes, dashes, etc.\n\n``` yaml\ntypographer: true # Substitution of common typographical elements will take place.\n    ## OR\ntypographer: false # No substitution, so dumb quotes will remain dumb quotes, etc.\n```\n\n#### quotes\n\nDefines the double and single quotes used for substituting dumb quotes if typographer is set to `true`.\n\n``` yaml\nquotes: '“”‘’' # \"double\" will be turned into “single”\n               # 'single' will be turned into ‘single’\n    ## OR\nquotes: '«»“”' # \"double\" will be turned into «single»\n               # 'single' will be turned into “single”\n```\n\n#### Example configuration\n\n``` yaml\nmarkdown:\n  render:\n    html: true\n    xhtmlOut: false\n    breaks: false\n    linkify: true\n    typographer: true\n    quotes: '“”‘’'\n```\n\n### Manage rules\n\nCertain rules are enabled or disabled depending on the [preset](#preset-options). For example, \"zero\" preset disables all rules, to enable specific rules:\n\n``` yml\nmarkdown:\n  preset: 'zero'\n\n  # Single rule\n  enable_rules: 'link'\n\n  # Multiple rules\n  enable_rules:\n    - 'link'\n    - 'image'\n```\n\n\"default\" preset enables all rules, to disable specific rules:\n\n``` yml\nmarkdown:\n  preset: 'default'\n\n  # Single rule\n  disable_rules: 'link'\n\n  # Multiple rules\n  disable_rules:\n    - 'link'\n    - 'image'\n```\n\n#### Available rules\n\nSince the rules are subject to change, it's better to check the Markdown-it's source code for up-to-date rules. Look for the `_rules` variable in the following files:\n- [parser_block.js](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_block.js)\n- [parser_core.js](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_core.js)\n- [parser_inline.js](https://github.com/markdown-it/markdown-it/blob/master/lib/parser_inline.js)\n\n### Automatic Headline ID's\n\nEnables you to automatically create ID's for the headings so you can link back to them. A valid html document cannot have two elements with duplicate id value, for example if `title` id is already used, subsequent `title` values will be updated to `title-2`, `title-3` and so on.\n\nDefault options:\n\n``` yaml\nmarkdown:\n  anchors:\n    # Minimum level for ID creation. (Ex. h2 to h6)\n    level: 2\n    # A suffix that is prepended to the number given if the ID is repeated.\n    collisionSuffix: ''\n    # If `true`, creates an anchor tag with a permalink besides the heading.\n    permalink: false\n    # Class used for the permalink anchor tag.\n    permalinkClass: header-anchor\n    # Set to 'right' to add permalink after heading\n    permalinkSide: 'left'\n    # The symbol used to make the permalink\n    permalinkSymbol: ¶\n    # Transform anchor to (1) lower case; (2) upper case\n    case: 0\n    # Replace space with a character\n    separator: '-'\n```\n\n### Plugins\n\nIncluded plugins:\n- markdown-it-abbr\n- markdown-it-attrs\n- markdown-it-cjk-breaks\n- markdown-it-container\n- markdown-it-deflist\n- markdown-it-emoji\n- markdown-it-footnote\n- markdown-it-ins\n- markdown-it-mark\n- markdown-it-sub\n- markdown-it-sup\n\nPlugins are not enabled by default, to enable:\n\n``` yaml\nmarkdown:\n  plugins:\n    - markdown-it-abbr\n    # installed external plugins also can be enabled\n    - markdown-it-table-of-contents\n```\n\n#### Plugin option\n\n``` yaml\nmarkdown:\n  plugins:\n    - name: 'markdown-it-emoji'\n      options:\n        shortcuts:\n          laughing: ':D'\n    - name: 'other-plugin'\n      options: ...\n```\n\n## Extensibility\n\nThis plugin overrides some default behaviors of how markdown-it plugin renders the markdown into html, to integrate with the Hexo ecosystem. It is possible to override this plugin too, without resorting to forking the whole thing.\n\nFor example, to enable [unsafe links](https://markdown-it.github.io/markdown-it/#MarkdownIt.prototype.validateLink) (which is disabled by default):\n\n``` js\nhexo.extend.filter.register('markdown-it:renderer', function(md) {\n  const { config } = this; // Optional, parse user config from _config.yml\n  md.validateLink = function() { return true; };\n});\n\n// Specify custom function in plugin option\nconst { slugize } = require('hexo-util');\nconst opts = hexo.config.markdown.anchors;\nconst mdSlugize = (str) =\u003e {\n  return slugize(str, { transform: opts.case, ...opts });\n};\n\nhexo.extend.filter.register('markdown-it:renderer', function(md) {\n  md.use(require('markdown-it-table-of-contents'), {\n    includeLevel: [2,3,4],\n    slugify: mdSlugize\n  });\n});\n```\n\nSave the file in \"scripts/\" folder and run Hexo as usual.\n\nRefer to markdown-it [API documentation](https://markdown-it.github.io/markdown-it/#MarkdownIt).\n\n## Frequently Asked Questions\n\n### Missing Styles of GFM Task Lists\n\nIn general, adding the following styles to the theme can solve the problem.\n\n```css\nli.task-list-item {\n  list-style-type: none;\n}\n\nli.task-list-item .task-list-item-checkbox {\n  margin: 0 0.2em 0.25em -1.6em;\n}\n```\n\n### How can I add math support?\n\nFirst, install KaTeX plugin for markdown-it.\n\n```bash\nnpm install katex @renbaoshuo/markdown-it-katex\n```\n\nThen add [`@renbaoshuo/markdown-it-katex`](https://github.com/renbaoshuo/markdown-it-katex) to plugins list.\n\n```yaml\nplugins:\n  - '@renbaoshuo/markdown-it-katex'\n  # Other plugins...\n```\n\nIf you need to allow spaces before and after delimiters (e.g. `$ 1 + 1 = 2 $`), set the `skipDelimitersCheck` option to `true`:\n\n```yaml\nplugins:\n  - name: '@renbaoshuo/markdown-it-katex'\n    options:\n      skipDelimitersCheck: true\n```\n\nDon't forget to include the KaTeX stylesheet in your html:\n\n```html\n\u003clink\n  rel=\"stylesheet\"\n  href=\"https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css\"\n/\u003e\n```\n\n### How can I merge table cells with the same content?\n\nInstall the [`markdown-it-merge-cells`](https://github.com/Menci/markdown-it-merge-cells) plugin.\n\n```bash\nnpm install markdown-it-merge-cells\n```\n\nThen add the plugin to plugins list.\n\n```yaml\nplugins:\n  - markdown-it-merge-cells\n  # Other plugins...\n```\n\n## Requests and bug reports\n\nIf you have any feature requests or bugs to report, you're welcome to [file an issue](https://github.com/hexojs/hexo-renderer-markdown-it/issues).\n\n\n[CommonMark]: http://commonmark.org/\n[Markdown]: http://daringfireball.net/projects/markdown/\n[GFM]: https://help.github.com/articles/github-flavored-markdown/\n[Markdown-it]: https://github.com/markdown-it/markdown-it\n[Hexo]: http://hexo.io/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexojs%2Fhexo-renderer-markdown-it","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhexojs%2Fhexo-renderer-markdown-it","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhexojs%2Fhexo-renderer-markdown-it/lists"}