{"id":15048407,"url":"https://github.com/myl7/remark-github-beta-blockquote-admonitions","last_synced_at":"2025-04-30T08:24:05.000Z","repository":{"id":57702270,"uuid":"497211662","full_name":"myl7/remark-github-beta-blockquote-admonitions","owner":"myl7","description":"remark plugin to add support for GitHub beta blockquote-based admonitions","archived":false,"fork":false,"pushed_at":"2024-09-19T12:59:51.000Z","size":357,"stargazers_count":24,"open_issues_count":1,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-20T17:01:51.895Z","etag":null,"topics":["admonitions","github","markdown","remark","remark-plugin"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/remark-github-beta-blockquote-admonitions","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/myl7.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":"2022-05-28T04:23:42.000Z","updated_at":"2024-11-13T11:34:17.000Z","dependencies_parsed_at":"2023-12-08T09:25:15.145Z","dependency_job_id":"f729efe9-3fae-44de-a136-22a220ca9a68","html_url":"https://github.com/myl7/remark-github-beta-blockquote-admonitions","commit_stats":{"total_commits":75,"total_committers":4,"mean_commits":18.75,"dds":"0.16000000000000003","last_synced_commit":"0b6eb5dd3c2937e2ea32509236883af2514b56f2"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myl7%2Fremark-github-beta-blockquote-admonitions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myl7%2Fremark-github-beta-blockquote-admonitions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myl7%2Fremark-github-beta-blockquote-admonitions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/myl7%2Fremark-github-beta-blockquote-admonitions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/myl7","download_url":"https://codeload.github.com/myl7/remark-github-beta-blockquote-admonitions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251667313,"owners_count":21624466,"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":["admonitions","github","markdown","remark","remark-plugin"],"created_at":"2024-09-24T21:11:28.555Z","updated_at":"2025-04-30T08:24:04.979Z","avatar_url":"https://github.com/myl7.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# remark-github-beta-blockquote-admonitions\n\nremark plugin to add support for [GitHub beta blockquote-based admonitions](https://github.com/github/feedback/discussions/16925)\n\nIf you are viewing the README on NPM, refer to [GitHub README](https://github.com/myl7/remark-github-beta-blockquote-admonitions#readme) for possible documentation update\n\n## Install\n\nThis package is [ESM only][esm].\nIn Node.js (version 16+), install with [npm]:\n\n```sh\nnpm install remark-github-beta-blockquote-admonitions\n```\n\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n[npm]: https://docs.npmjs.com/cli/install\n\n## Get Started\n\n```js\nimport plugin from 'remark-github-beta-blockquote-admonitions'\n\nconst options = {} // Plugin options\nconst html = String(\n  await remark().use(remarkParse).use(plugin, options).use(remarkRehype).use(rehypeStringify).process(`\\\n# Admonitions\n\u003e [!NOTE]\n\u003e test\n`),\n)\n```\n\nThe output HTML will be:\n\n```html\n\u003ch1\u003eAdmonitions\u003c/h1\u003e\n\u003cdiv class=\"admonition\"\u003e\n  \u003cp class=\"admonition-title\"\u003eNOTE\u003c/p\u003e\n  \u003cp\u003etest\u003c/p\u003e\n\u003c/div\u003e\n```\n\nThe legacy ones with titles like `**Note**` is also and still supported.\nUse the option `legacyTitle` to enable it.\n\n## Config\n\n```ts\nexport interface Config {\n  classNameMaps: {\n    // Classes the `\u003cdiv\u003e` block should be added with\n    block: string | string[] | (title: string) =\u003e (string | string[])\n    // Classes the `\u003cp\u003e` title should be added with\n    title: string | string[] | (title: string) =\u003e (string | string[])\n  }\n  // Which title texts in `\u003cp\u003e` should make the block considered as admonitions.\n  // This is performed before any other actions, e.g., it gets `[!NOTE]`.\n  titleFilter: string[] | (title: string) =\u003e boolean\n  // The function allows you to differ displayed title text in the output with\n  // the one checked in the plugin such as the classes the plugin is going to\n  // add.\n  // The differing is done after the filter check.\n  // This may help you to embed custom title text with particular admonition\n  // type like \"[!Note/My Title]\".\n  // By default, both two variables use the same value with the prefix`[!` and\n  // suffix `]` trimmed.\n  titleTextMap: (title: string) =\u003e { displayTitle: string; checkedTitle: string }\n  // Customize block node and title node data in mdast syntax tree.\n  // For example, if you want the block to be `\u003cadmonition\u003e` other than `\u003cdiv\u003e`,\n  // with [the help of remark-rehype], you can set `{ hName: 'admonition' }` for\n  // block to implement it.\n  // By default, no extra actions.\n  //\n  // [the help of remark-rehype]: https://github.com/syntax-tree/mdast-util-to-hast#fields-on-nodes\n  dataMaps: {\n    block: (data: Data) =\u003e Data\n    title: (data: Data) =\u003e Data\n  }\n  // Whether to keep trailing whitespaces of titles, e.g., \"[!NOTE] \\r\\t\".\n  // Trimmed by default.\n  // There is rare need to change it unless you want to strictly control the\n  // syntax tree.\n  titleKeepTrailingWhitespaces: boolean\n\n  // To use the legacy titles like **Note**\n  legacyTitle: boolean\n  // The following options only take effects when `legacyTitle == true`.\n\n  // When enabled, the `\u003cstrong\u003e` element will be moved from `\u003cp\u003e` children to\n  // `\u003cblockquote\u003e` children with `\u003cp\u003e` wrapped, like the structure of MkDocs\n  // admonitions, otherwise no extra actions\n  titleLift: boolean\n  // When titleLift is enabled, after `\u003cstrong\u003e` is moved, the function defines\n  // what the whitespaces following the `\u003cstrong\u003e` will be converted to.\n  // By default, remove these whitespaces.\n  // You may rarely need to set the option unless want to strictly control the\n  // syntax tree.\n  titleLiftWhitespaces?: (whitespaces: string) =\u003e string\n  // When titleLift is enabled, other than wrapping `\u003cstrong\u003e` with `\u003cp\u003e`, use\n  // the title text to build a `\u003cp\u003e` with classes and put it into `\u003cblockquote\u003e`\n  // children to serve as admonition title, which makes the structure be like\n  // MkDocs admonitions more\n  titleUnwrap: boolean\n}\n```\n\nThe detailed default configuration is:\n\n```js\nexport const defaultConfig: Config = {\n  classNameMaps: {\n    block: 'admonition',\n    title: 'admonition-title',\n  },\n  titleFilter: ['[!NOTE]', '[!IMPORTANT]', '[!WARNING]', '[!TIP]', '[!CAUTION]'],\n  titleTextMap: (title) =\u003e ({\n    // To remove the `[!` prefix and `]` suffix\n    displayTitle: title.substring(2, title.length - 1),\n    checkedTitle: title.substring(2, title.length - 1),\n  }),\n  dataMaps: {\n    block: (data) =\u003e data,\n    title: (data) =\u003e data,\n  },\n  titleKeepTrailingWhitespaces: false,\n  legacyTitle: false,\n}\n```\n\nNotice: The default config and provided config are merged simply with `{ ...a, ...b }`, so for example if you are going to provide a customized `classNameMaps`, you need to provide both `block` and `title`.\n\n## How To\n\n### Collaborate with MkDocs admonitions?\n\n[MkDocs admonitions](https://www.markdownguide.org/tools/mkdocs/#using-admonitions) is just [Python-Markdown admonitions](https://python-markdown.github.io/extensions/admonition/) which is from [rST-style admonitions](https://docutils.sourceforge.io/docs/ref/rst/directives.html#specific-admonitions)\n\nA MkDocs-campatibility-focused config `mkdocsConfig` is already provided within the package.\nThe config will make the output HTML the same as the MkDocs admonition HTML.\nCustom admonition types are also supported by prefixing it with `admonition:` and a space.\nExamples are:\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003eGitHub beta blockquote-based\u003c/td\u003e\n    \u003ctd\u003eMkDocs\u003c/td\u003e\n    \u003ctd\u003eHTML\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n\n```md\n\u003e [!note danger \"Don't try this at home\"]\n\u003e You should note that the title will be automatically capitalized.\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n\u003c!-- prettier-ignore --\u003e\n```md\n!!! note danger \"Don't try this at home\"\n    You should note that the title will be automatically capitalized.\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n```html\n\u003cdiv class=\"admonition note danger\"\u003e\n  \u003cp class=\"admonition-title\"\u003eDon't try this at home\u003c/p\u003e\n  \u003cp\u003eYou should note that the title will be automatically capitalized.\u003c/p\u003e\n\u003c/div\u003e\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n    \u003ctd\u003e\n\n```md\n\u003e [!admonition: guess \"Don't try this at home\"]\n\u003e You should note that the title will be automatically capitalized.\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n\u003c!-- prettier-ignore --\u003e\n```md\n!!! guess \"Don't try this at home\"\n    You should note that the title will be automatically capitalized.\n```\n\n\u003c/td\u003e\u003ctd\u003e\n\n```html\n\u003cdiv class=\"admonition guess\"\u003e\n  \u003cp class=\"admonition-title\"\u003eDon't try this at home\u003c/p\u003e\n  \u003cp\u003eYou should note that the title will be automatically capitalized.\u003c/p\u003e\n\u003c/div\u003e\n```\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nNotice: Descriptive title in `\"\"` is required, otherwise it will fallback to empty string `\"\"` other than names corresponding to the types like `Notes` to `note`.\n\n## Mismatch\n\nThe GitHub implementation (so far) will turn \"NOTE\", \"IMPORTANT\", \"WARNING\" to \"Note\", \"Important\", \"Warning\" respectively, but this library will keep the original UPPERCASE form.\nThis is because this library considers more possible admonition titles like `警告`, `訓戒`, `훈계`, `замечание`, `عتاب` via custom options.\nIt is hard to determine whether they can be lowercased and what it should be if any.\n\nThe GitHub implementation that includes the '14 November 2023' update prevents alerts (a.k.a. admonitions here, not just the alert varient) from being nested within other elements, but this library does not check that.\nThis is because this library does not consider the final view of the admonitions, which can be the reason why GitHub checks it.\nAnd you can also easily select the GitHub-expected admonitions via CSS selectors from all ones, while it is hard in the opposite way.\n\n## Compatibility\n\n**v1 -\u003e v2.0.0**: To avoid breaking previous code that uses titles `**Note**`, you only need to add the option `legacyTitle: true`, replace `mkdocsConfig` with `mkdocsConfigForLegacyTitle`, and no other changes are required.\nv2.0.0 is served as an intermediate stage for users who want to support the new title syntax without breaking previous code with minimal changes.\n\n**v2.0.0 -\u003e v2**: The `titleFilter` will be performed before any other actions including `titleTextMap`.\nIf you just use the default configuration, no changes are required.\nIf your `titleTextMap` returns `checkedTitle` (i.e., the 2nd returned value) as `title` is, for previous v1 code no changes are required.\nOtherwise, since previously `titleFilter` checks `checkedTitle`, now it will check the original `title` (e.g., `[!NOTE]` / `[!admonition: note]`) directly (for both the default `[!NOTE]` title and legacy `**Note**` title).\nYou may need to update the value of `titleFilter`.\n\n**v2 -\u003e v3 (latest)**: While no breaking changes are introduced by this package, we update the dependencies of the remark/rehype/unist ecosystems to the next major versions:\n\n- Dependencies:\n  - unist-util-visit: v4 -\u003e v5\n- Dev dependencies:\n  - rehype-stringify: v9 -\u003e v10\n  - remark: v14 -\u003e v15\n  - remark-parse: v10 -\u003e v11\n  - remark-rehype: v10 -\u003e v11\n  - unified: v10 -\u003e v11\n\nThe most notable change of this major version update of these ecosystems IMO is dropping Node 12 support and requiring Node 16+, which is already required by this package due to ESM only.\n\nWe still maintain v2 of this package, hosted in the `oldstable` branch.\nLatest changes will be downstreamed to v2 with best effort.\nOur purpose of keeping v2 is to support some \"slow\" packages better like [next-mdx-remote].\n\n[next-mdx-remote]: https://github.com/hashicorp/next-mdx-remote\n\n## Implementation\n\nSince GitHub beta blockquote-based admonitions are backward compatible in Markdown, things are simple, which are just to visit the matched elements in the `remark-parse` parsed syntax tree to add `remark-rehype` recognizable classes\n\n## License\n\nCopyright (C) myl7\n\nSPDX-License-Identifier: Apache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmyl7%2Fremark-github-beta-blockquote-admonitions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmyl7%2Fremark-github-beta-blockquote-admonitions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmyl7%2Fremark-github-beta-blockquote-admonitions/lists"}