{"id":19858695,"url":"https://github.com/about-code/glossarify-md","last_synced_at":"2025-05-02T02:31:14.559Z","repository":{"id":35115057,"uuid":"203664408","full_name":"about-code/glossarify-md","owner":"about-code","description":"A Term-to-Definition-Linker for Markdown. https://npmjs.com/package/glossarify-md","archived":false,"fork":false,"pushed_at":"2024-01-27T14:02:52.000Z","size":2388,"stargazers_count":31,"open_issues_count":3,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-07T12:49:30.269Z","etag":null,"topics":["documentation","glossary","link","markdown","taxonomy","taxonomy-terms","terminology","terminology-management","vuepress","writing"],"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/about-code.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","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}},"created_at":"2019-08-21T21:06:07.000Z","updated_at":"2024-10-30T16:16:35.000Z","dependencies_parsed_at":"2024-01-12T04:44:31.723Z","dependency_job_id":"dc2b8e6a-5a1b-4073-8663-06b50381952e","html_url":"https://github.com/about-code/glossarify-md","commit_stats":{"total_commits":536,"total_committers":3,"mean_commits":"178.66666666666666","dds":0.03358208955223885,"last_synced_commit":"a5a03782474ed4597c0e1a4d8d35cf9f0d3f350d"},"previous_names":[],"tags_count":60,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/about-code%2Fglossarify-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/about-code%2Fglossarify-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/about-code%2Fglossarify-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/about-code%2Fglossarify-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/about-code","download_url":"https://codeload.github.com/about-code/glossarify-md/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251972475,"owners_count":21673612,"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":["documentation","glossary","link","markdown","taxonomy","taxonomy-terms","terminology","terminology-management","vuepress","writing"],"created_at":"2024-11-12T14:24:16.457Z","updated_at":"2025-05-02T02:31:09.546Z","avatar_url":"https://github.com/about-code.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# glossarify-md\n\n![Tests (Functional)](https://github.com/about-code/glossarify-md/workflows/Tests%20\\(Functional\\)/badge.svg)\n![Nightly Tests (Latest Dependencies)](https://github.com/about-code/glossarify-md/workflows/Tests%20\\(with%20latest%20deps\\)/badge.svg)\n\n[CommonMark]: https://www.commonmark.org\n\n[doc-ambiguity]: https://github.com/about-code/glossarify-md/blob/master/doc/ambiguity.md\n\n[doc-book-index]: https://github.com/about-code/glossarify-md/blob/master/doc/gen-book-index.md\n\n[doc-config]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md\n\n[doc-cross-linking]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md\n\n[doc-extended]: https://github.com/about-code/glossarify-md/blob/master/doc/README.md\n\n[doc-options]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md\n\n[doc-paths-and-urls]: https://github.com/about-code/glossarify-md/blob/master/doc/paths-and-urls.md\n\n[doc-syntax-extensions]: https://github.com/about-code/glossarify-md/blob/master/doc/markdown-syntax-extensions.md\n\n[doc-term-attributes]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md\n\n[doc-vocabulary-uris]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md\n\n[doc-vuepress]: https://github.com/about-code/glossarify-md/blob/master/doc/use-with-vuepress.md\n\n[GFM]: https://github.github.com/gfm/\n\n[glob]: https://github.com/isaacs/node-glob#glob-primer\n\n[glossarify-md]: https://github.com/about-code/glossarify-md\n\n[Hugo]: https://gohugo.io\n\n[link reference definitions]: https://spec.commonmark.org/0.30/#link-reference-definition\n\n[node.js with npm]: https://nodejs.org\n\n[pandoc]: https://pandoc.org\n\n[pandoc-heading-ids]: https://pandoc.org/MANUAL.html#heading-identifiers\n\n[unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md\n\n[vuepress]: https://vuepress.vuejs.org\n\n[YAML]: https://yaml.org\n\n[glossarify-md] is a command line tool to help Markdown writers with\n\n- **Cross-Linking** (prime use case): auto-link terms to some definition in a glossary\n- **Indexes**: generate indexes from glossary terms and navigate to where they were mentioned\n- **Lists**: generate arbitrary lists such as *List of Tables*, *List of Figures*, *List of Listings*, *List of Definitions*, *List of Formulas*, and so forth...\n\n## Table of Contents\n\n- [Prerequisites](#prerequisites)\n- [Install](#install)\n- [Configuration](#configuration)\n- [Sample](#sample)\n  - [Input](#input)\n  - [Output](#output)\n- [What's not being linkified](#whats-not-being-linkified)\n- [Aliases and Synonyms](#aliases-and-synonyms)\n- [Term Hints](#term-hints)\n- [Multiple Glossaries](#multiple-glossaries)\n- [Sorting Glossaries](#sorting-glossaries)\n- [Advanced Topics](#advanced-topics)\n- [Node Support Matrix](#node-support-matrix)\n- [Special Thanks go to](#special-thanks-go-to)\n- [License](#license)\n\n## Prerequisites\n\n- [node.js with npm]\n\n## Install\n\n#### Option 1: Install *locally*, init, configure, run (recommended):\n\n```\ncd ./your-project\nnpm install glossarify-md\n\nnpx glossarify-md --init --new --local\nnpx glossarify-md --config ./glossarify-md.conf.json\n```\n\n\u003e **ⓘ Since 6.3.0** glossarify-md supports a `--watch` mode.\n\nWhen installing locally you might want to set up a shortcut by adding a run script to your `package.json`:\n\n```json\n{\n  \"scripts\": {\n    \"glossarify\": \"glossarify-md --config ./glossarify-md.conf.json\"\n  }\n}\n```\n\nNext time you're able to use:\n\n```\nnpm run glossarify\n```\n\n#### Option 2: Install *globally*, init, configure, run:\n\n```\nnpm install -g glossarify-md\n\nglossarify-md --init --new\nglossarify-md --config ./glossarify-md.conf.json\n```\n\n## Configuration\n\nBy following the installation instructions you should be set up with a minimal configuration:\n\n*Minimal Configuration*\n\n```json\n{\n  \"$schema\": \"./node_modules/glossarify-md/conf/v5/schema.json\",\n  \"baseDir\": \"./docs\",\n  \"outDir\": \"../docs-glossarified\"\n}\n```\n\n**[More configuration options here][doc-config]**.\n\n## Sample\n\n[Sample]: #sample\n\nWe assume a sample project with the following structure:\n\n```\n${root}\n   +- docs/\n   |    +- pages/\n   |    |    |- page1.md\n   |    |    `- page2.md\n   |    |\n   |    |- README.md\n   |    |- who-icd-codes.md\n   |    `- glossary.md\n   |\n   +- docs-glossarified/  (Generated output directory)\n   `- glossarify-md.conf.json\n```\n\n### Input\n\nA term *Term* then may occur anywhere in your file set:\n\n*./docs/pages/page1.md...*\n\n```md\n# Document\n\nThis is a text mentioning a glossary Term to describe something.\n```\n\nYour glossary is a file with terms being section headings and definitions being section content:\n\n*docs/glossary.md*\n\n```md\n# Glossary\n\n## Term\n\nA glossary term has a short description. The full description contains both sentences.\n```\n\nThen run [glossarify-md] with a [glossarify-md.conf.json](#configuration):\n\n```\nnpx glossarify-md --config ./glossarify-md.conf.json\n```\n\n### Output\n\nAugmented versions of your input files have been written to the output directory:\n\n*Source: ./docs-glossarified/pages/page1.md*\n\n```md\n# [Document](#document)\n\nThis is text mentioning a glossary [Term][1] to describe something.\n\n[1]: ../glossary.md#term \"A glossary term has a short description.\"\n```\n\n*Source: ./docs-glossarified/glossary.md*:\n\n```md\n# [Glossary](#glossary)\n\n## [Term](#term)\n\nA glossary term has a short description. The full description contains both sentences.\n```\n\nWhen rendered by some Markdown to HTML converter (not part of glossarify-md) the result may look like this:\n\n*./docs-glossarified/glossary.html*:\n\n\u003e ## [Glossary](#glossary)\n\u003e\n\u003e ### [Term](#term)\n\u003e\n\u003e A glossary term has a short description. The full description contains both sentences.\n\n*./docs-glossarified/pages/page1.html*\n\n\u003e ## [Demo](#demo)\n\u003e\n\u003e This is text mentioning a glossary [Term][1] to describe something.\n\u003e\n\u003e [1]: #term \"A glossary term has a short description.\"\n\nTo navigate the opposite direction from a term to sections where a glossary term got mentioned you might want to generate a [Book Index][doc-book-index].\n\n## What's not being linkified\n\nSome syntactic positions of a term occurrence are **excluded** from being linked to the glossary, for example when the term occurs in:\n\n- HTML `\u003ca\u003etext\u003c/a\u003e`\n- Headlines `#`\n- (Markdown) links `[]()`\n- Preformatted blocks ` ```, ~~~ `\n- Blockquotes `\u003e`\n  - Blockquotes are excluded based on the premise that a quoted entity may not share the same definition of a term like the entity who quotes it.\n\n\u003e **ⓘ Tip:**  Wrap a word into some pseudo HTML tag like e.g. `\u003cx\u003eword\u003c/x\u003e` to mark it for exclusion from [term-based auto-linking][doc-cross-linking].\n\n## Aliases and Synonyms\n\n[alias]: #aliases-and-synonyms\n\n[aliases]: #aliases-and-synonyms\n\nAliases can be added by what we call [*term attributes*][doc-term-attributes]. Term attributes are provided in a [YAML] formatted comment following a term's heading. For aliases there's the term attribute `aliases` whose attribute value is a string of comma-separated synonyms:\n\n*glossary.md with a term attribute `aliases`:*\n\n```md\n# Glossary\n\n## Cat\n\u003c!-- aliases: Cats, Wildcat, House Cat, PET-2 --\u003e\nCats are cute, ...dogs are loyal.\n```\n\nIn the output files aliases will be linked to their related term:\n\n*./docs-glossarified/pages/page2.md*\n\n```md\n# About Cats\n\n[Cats](./glossary.md#cat) and kitten almost hidden spotting mice of any size. [Andreas Martin]\n```\n\n\u003e **ⓘ Note:** [YAML] syntax is *case-sensitive* as well as *sensitive to tabs and whitespaces*. In general term attributes will be lowercase.\n\n## Term Hints\n\n*glossarify-md.conf.json*\n\n```json\n\"glossaries\": [\n    { \"file\": \"./glossary.md\", \"termHint\": \"↴\"},\n]\n```\n\nGlossaries can be associated with *term hints*. Term hints may be used to indicate that a link refers to a glossary term and in case of [multiple glossaries][multiple-glossaries] to which one. Use `\"${term}\"` to control placement of a `termHint`. For example, `\"☛ ${term}\"` puts the symbol `☛` in front of a linkified term occurrence.\n\n## Multiple Glossaries\n\n[multiple-glossaries]: #multiple-glossaries\n\nSometimes you might whish to have multiple glossaries:\n\n*glossarify-md.conf.json*\n\n```json\n\"glossaries\": [\n    { \"file\": \"./glossary.md\",   \"termHint\": \"↴\" },\n    { \"file\": \"./who-icd-codes.md\", \"termHint\": \"⚕${term}\" }\n]\n```\n\n*who-icd-codes.md*\n\n```md\n## NC32\nFracture of forearm\n\n## NC90\nSuperficial injury of knee or lower leg\n\n```\n\nWith adding *who-icd-codes.md* to the list of glossaries every mention of [⚕NC32](#nc32 \"Fracture of forearm\") or [⚕NC90](#nc90 \"Superficial injury of knee or lower leg\") in documents will have a tooltip and link to the glossary definition, too.\n**Since v5.0.0** `file` can also be used with a [glob] file pattern:\n\n```json\n\"glossaries\": [\n    { \"file\": \"./**/*.md\" },\n]\n```\n\nThis way each markdown file matching the pattern will be processed like a glossary. More see [Cross-Linking][doc-cross-linking] and [Multiple Glossaries and Ambiguity][doc-ambiguity].\n\n\u003e **ⓘ Note:** `termHint` only works for `file` pointing at a particular file name.\n\n## Sorting Glossaries\n\nAdd `sort` with `\"asc\"` (ascending) or `\"desc\"` (descending) to glossaries you want [glossarify-md] sort for you:\n\n*glossarify-md.conf.json*\n\n```json\n\"glossaries\": [\n    { \"file\":\"./glossary.md\", \"sort\": \"asc\" }\n]\n```\n\nInternally, glossarify-md uses `Intl.Collator` and falls back to `String.localeCompare` if the `Intl` API is missing. You can tweak collation by adding `i18n` options:\n\n*glossarify-md.conf.json*\n\n```json\n\"i18n\": {\n   \"locale\": \"de\",\n   \"ignorePunctuation\": true\n}\n```\n\nThe `i18n` object is passed *as is* to the collator function. Thus you can use additional options documented on [Mozilla Developer Portal](https://developer.mozilla.org/de/docs/Web/JavaScript/Reference/Global_Objects/Collator):\n\n## [Advanced Topics][doc-extended]\n\nSee **[here][doc-extended]**, for advanced topics:\n\n- Importing and exporting terms\n- Generating files, such as a book index, lists of figures, etc.\n- Cross-Linking more than just terms\n- Using glossarify-md with other tools, like [vuepress], [pandoc] or [Hugo]\n- Dealing with non-standard Markdown Syntax via Plug-ins (e.g Frontmatter)\n\n## Node Support Matrix\n\nThe term *support* refers to *runs on the given platform* and is subject to the terms and conditions in [LICENSE](#license).\n\n| NodeJS  | glossarify-md |                                                                           Current Test Matrix                                                                            |\n| ------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| Current | v7            | Tested. Should node.js introduce breaking changes which affect [glossarify-md], then we may choose to step back from supporting *Current* until it becomes the next LTS. |\n| 18 LTS  | v6, v7        | Tested + Supported\n| 16 LTS  | v5, v6, v7    | Tested + Supported                                                                                                                                                       |\n| 14 LTS  | v4, v5, v6    | |\n| 12 LTS  | v3, v4, v5    |                                                                                                                                                                          |\n| 10 LTS  | v2, v3, v4    |                                                                                                                                                                          |\n\n## Special Thanks go to\n\n- [John Gruber](https://daringfireball.net/projects/markdown/), author of the Markdown syntax\n- [John MacFarlane  et al.](https://github.com/commonmark-spec), initiators and authors of the CommonMark specification\n- [Titus Wormer](https://github.com/wooorm), author of [unifiedjs](https://unifiedjs.com/), [remarkjs](https://github.com/remarkjs) and so much more\n- All the other great people publishing modules of value for the tool, be it directly or transitively.\n\n## License\n\n[MIT](LICENSE) © [Andreas Martin](https://github.com/about-code)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabout-code%2Fglossarify-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabout-code%2Fglossarify-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabout-code%2Fglossarify-md/lists"}