about-code/glossarify-md

A Term-to-Definition-Linker for Markdown. https://npmjs.com/package/glossarify-md

glossarify-md's Issues

footnotes stop working, when using glossarify

Hi,

I am using vuepress 1.1.0 with markdown-it-footnote 3.0.2.

When activating glossarify (2.0.0) - footnotes stop working, i.e. [^footnote1] is displayed verbatim instead of being a link.

Linkify term usage in term definitions, too.

User Story

As a writer...

1. ... when defining a glossary term A by mentioning another term B in the same glossary G, I want the occurrence of term B in the definition of A to be linked to the definition of B.
2. ... when defining a glossary term C in glossary G(C) by mentioning another term D of a different glossary G(D), I want the occurrence of D in the definition of C to be linked to the definition of D in glossary G(D).

Provide example for use with vuepress

User Story

As user of vuepress I would like to know how to make use of glossarify-md to generate vuepress books with glossary references.

vuepress is presumably one of the most promising alternatives to gitbook, the latter being no longer maintained. vuepress does not have glossary support at the moment which poses a barrier for users in need to migrate away from gitbook. As a command line tool and npm package glossarify-md can be integrated as a pre-processor into a vuepress build pipeline.

A documented sample or demo-project shall provide guidance on how to use glossarify-md with vuepress.

Generate list of tables

User Story

As a writer I would like to generate a file where any tables in documents are listed with some description and a link to where they were defined.

Index: Allow to configure heading depth for less cluttered index file

User Story

Today when generating an index file for glossary terms, the generated file will list terms and for each term all the headings directly preceding the paragraph of occurrence. While this allows to jump precisely to the location where a term was used, it clutters the index with seemingly unrelated headings.

As a writer I would like to be able to declare that the index should only link to headings of a particular depth, e.g. document titles (headings of depth 1) and want the system to generate superscript links to the sections of occurrence (depth > 1).

Example 1: depth: 1 generates links to document titles and links to deeper document sections as superscript links

Index

My Term

Chapter 1 - Chapter 2 ^{1, 2, 3} - Chapter 3

Example 2: depth: 2 generates links to headings at depth 2 and superscript links to headings of depth > 2

Index

My Term

Section 1 - section 2 ¹ - Section 3

Sort terms in a glossary

Would be great to be able to sort the terms in the target output.

Config option 'generateFiles.indexFile': drop support for value range 'string'.

See also CHANGELOG.md/v3.1.0/Deprecation Notices

Glossary-terms flanked by ( or ) wouldn't get linked

Hi,

I am using glossrify-md v2.0.0 together with vuepress 1.0.0.

I've a term "SC" which will get linked to in
(OnPremises SC↵ or other stuff)

but it wouldn't in
(OnPremises SC)

List of listings

User Story

As a writer I would like to generate a file where any listings in documents are listed with some description and a link to where they were defined.

minimist-options 4.1.0 breaks glossarify-md

glossarify-md depends on minimist-options: "^4.0.1".

With minimist-options 4.1.0 any versions of glossarify-md 3.6.3 and earlier break on fresh installs (without an existing package-lock.json).

When running glossarify-md it exits with:

.../node_modules/minimist-options/index.js:101
   throw new TypeError(`Expected "${key}" default value to be of type "${expectedType}", got ${prettyPrint(defaultType)}`);


Expected "glossaries" default value to be of type "string-array", got "object-array"
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] test_02: `npx . --config ./input/markdown/glossarify-md.conf.json`
npm ERR! Exit status 1
npm ERR! 

glossaries is an option derived from a JSON-Schema property where default is an object array:

conf.schema.json

"glossaries": {
    "description": "An array of glossaries. Allows for different kinds of glossaries and definitions.",
     "type": "array",
     "items": {
          "$ref": "#/$defs/GlossariesOpts"
      },
      "alias": "g",
      "default": [
          { "file": "./glossary.md", "termHint": ""}
      ]
},

The default value is passed to minimist-options. This used to work prior to minimist-options 4.1.0.

Hotfixes available:

• v3: glossarify-md v3.6.4
• v2: glossarify-md v2.1.2

Hotfix versions nail minimist-options to version 4.0.1. Please uninstall older versions and install the given versions.

Terms with leading or trailing non-ASCII chars not linked

Reproduction

glossary.md

## äöüß at the beginning of a term
Case 1

## at the end of a term with äöüß 
Case 2

document.md

Text with 'äöüß at the beginning of a term' or 'at the end of a term with äöüß'

... won't link the terms in the text to their glossary definition.

First analysis

Terms in glossaries are searched by a JavaScript regular expression with a \b word boundary character class, e.g. "\\b(äöuß at the beginning of a term)\\b". Character classes in JS RegExps don't support unicode, though, so Umlauts at the beginning or end of the expression aren't recognized as word boundary characters.

While ES6/2015 introduces unicode support with the "u" flag, the flag does not affect character classes. They are still non-unicode to remain compatible with ES5 and before RegExps.

option to add inline title attribute to markdown link

Hi @about-code 👋

Really nice idea to put this into a common Markdown pipeline.

Markdown would allow adding a title attribute to links [1], what do you think
adding such [optional] functionality based on a flag/option?

expected behaviour ./out/files/file1.md

# Demo for a Glossary Term

This is a text which uses a [Glossary Term ↴](../glossary.md#glossary-term "A glossary term has a short description. The full description contains both sentences.") to describe something.

📝 [1] https://daringfireball.net/projects/markdown/syntax#link

v4: Prepare release

• add build status badges to README.md
• update CHANGELOG.md

Don't cut a term's short description on markdown formatting

Given a term definition

in/glossary.md

## Term

This is the term's *formatted* short description. 

and a document mentioning the term

in/document.md

This is a document mentioning Term.

then currently the actual output is:

out/document.md (actual)

This is a document mentioning [Term][1].

[1] ./glossary.md#term This is the term's

while expected output is:

out/document.md (expected)

This is a document mentioning [Term][1].

[1] ./glossary.md#term This is the term's formatted short description.

Setup CI pipeline with automated testing

User Story

As the project owner I want to have tests being run

• continuously
• on pushes
• on any branch
• on different versions of node
• on different OS platforms

to be able to be able to make quality assertions about the state of a commit or pull request and contributions.

Short description sometimes not correctly extracted

Current behavior (1)

Issue 1: Given a glossary term with a single sentence as its description, then this sentence is the long as well as the short description. Currently only the long description is correctly identified. The short description is (sometimes) not.

Expected behavior

Extract the short description also for single sentence descriptions.

Current behavior (2)

Issue 2: Given the first sentence of a description spans accross multiple lines. Then only the end of this sentence belonging to a single line is extracted as short description whereas parts of previous lines are not.

Expected behavior

Extract the full first sentence also for multi-line descriptions.

vuepress doc: build script must cd into target

Extract anchor labels with markdown formatting

Given a document with anchors

document.md

<a id="listing-foo">Anchor title with *formatted* word</a>

Some text

<a id="listing-foo">*Anchor title completely formatted*</a>

Some other text

and a configuration

glossarify-md.conf.json

generateFiles: {
   "listOf": [
       { "class": "listing", "file": "./listings.md" }
   ]
}

then glossarify-md should generate a list of listings with list items being links using the anchor text in plain text.

Upgrade remarkjs

Dependencies:

• remark-parse: ^8.0.0
  • replace remark-parse option footnotes: true with remark-footnotes processor plug-in where necessary (Changelog [email protected])
• remark-stringify: ^8.0.0
  • replace remark-stringify option footnotes: true with remark-footnotes processor plug-in where necessary (Changelog [email protected])
• remark-reference-links: ^5.0.0 (Changelog)
• remark-slug: ^6.0.0 (Changelog)
• remark-autolink-headings: ^6.0.0 (Changelog)

Dev. Dependencies:

• remark-cli: ^8.0.0
  • major version changes only due to dependencies to remarkjs@8 and unified@8. No CLI-specific migration steps

Full Changelog

Allow to add and link synonyms and variants to a definition

User Story

As a user I want to be able to add synonyms or different syntactical variants of a term to a definition such that any use of the synonym or syntactical variant in text will also be linked to the term definition.

Unclear how to disable reportNotMentioned

It seems to be true by default. But there is no config option to disable that. And the command line flag appears to be a boolean flag, which has no negative option (e.g. --no-reportNotMentioned).

My use case is to generate a glossary of terms, but there isn't any body of text attached to the terms. It's a set of industry terms that organization member should be familiar with, but not necessarily included into any text.

Thanks.

Generate list of figures

User Story

As a writer I would like to generate a file where any images referred to in documents are listed with their description and a link to where they were used.

glossarify-md breaks VuePress [[toc]] markdown extension

I am using glossarify-md in a VuePress based documentation. When using the [[toc]] markdown extension (see VuePress docs), after running npm run glossarify [[toc]] is getting escaped to \[[toc]] and thus not rendered correctly as a table of contents (just as plain text). I am using the latest version of glosssarify-md (3.6.2).

Headings with codespans cause error output

Given a glossary with a term

glossary.md

# Glossary

## Term
...a term

and a term-occurrence in a section with a headline containing a code-span

document.md

## `FooClass`

Term

Then when generating an index file with option generateFiles.indexFile the term produces an untitled index link reference

book-index.md

## Term 
[][9] 

[9]: ./glossary.md#term ... a term

which causes an error output by remark-stringify.

Aliases not working

I have this code in the glossary.md of my project.

## Issue
<!-- Aliases: Issues -->
Damit wird der Verstoß gegen eine SonarQube-Regel bezeichnet.

While the word "Issue" is found and linked to the glossatry without any problem, "Issues" is not found at all in any constellation.

Support Backlinks from definition to usage

User Story

As a user I want to have a link from the definition of a term to its occurrences in text.

Alternatively the software may offer an option to generate an index document which lists all glossary terms (without their detailed definition). Every term links to the term's glossary definition as well as to the parent section of the paragraph where it was found in text. The link to its definition may always be the first one. Multiple occurrences in the same section of a document only generate one section link in the index.

For example an index could look like

Index

• Hercules mentionend in
  • The Ancient Greeks
  • Greek Mythodology

Support for compact output with references

User Story

As a user of I want to choose between verbose and more compact output in order to improve file size and readability.

Verbose output

Verbose output should replace each occurence of a term with a glossary link pointing directly to the glossary.

WHEN IN plain text THEN "Lorem ipsum↴" MUST be linked directly to glossary.

WHEN IN plain text THEN "[Lorem ipsum↴](../glossary.md#lorem-ipsum)" MUST be linked directly to glossary.

Compact output uses references

Compact output uses references. Multiple occurrences of a term share a common relatively short reference number. The actual reference URL isn't replicated with each term but exists only once at the end of a document.

WHEN IN plain text THEN "Lorem ipsum↴" MUST be linked directly to glossary.

WHEN IN plain text THEN "[Lorem ipsum↴][1]" MUST be linked directly to glossary.
[1]: ../glossary.md#lorem-ipsum "Lorem ipsum ↴"

An implementation MAY use remark-reference-links as an optional post-processing step after linkification.

Cannot find module 'remark-stringify'

I've updated to v.3.6.0 in my VuePress driven documentation. Trying to call "npm run glossarify" results in error message stated above. I could help myself with installing module "remark-stringify".

Error log attached.
error-log.txt

Option: case-sensitivity

User Story

As a user I want to be able to configure whether terms should be matched against their definition in a glossary in a case-sensitive or case-insensitive manner.

Make baseDir relative to config file

User Story

• As a writer I don't want to deal with complex path configurations. As a writer I want to be sure relative paths in my config files are always relative to that config file.

• As a community-support I do not want to have to ask the support-requester what the current working directory was in which he or she has been running the tool. I want to besure relative paths in the requester's config file are relative to that config file.

• As a tester I want to be able to run the tool within its source directory and with config files in particular subdirectories. I want to be able to write config files which only process files relative to that config file. I want to be sure relative paths in my config file are always relative to that config file.

• As a writer, community-support, tester I want to make . the sane default for baseDir.

Index: term headings should be at depth 2

Bug

Actual

Index

Term 1

Section 1 - Section 2 - Section 2

Term 2

Section 2

Expected

Index

Term 1

Section 1 - Section 2 - Section 2

Term 2

Section 2

Correctly link to formatted term headings

Given a term definition

in/glossary.md

## `Formatted`

The term heading is formatted and put into codespan.

and a document mentioning the term

in/document.md

This is a document mentioning Formatted.

then currently the actual output is:

out/document.md (actual)

This is a document mentioning Formatted.

while expected output is:

out/document.md (expected)

This is a document mentioning [Formatted][1].

[1] ./glossary.md#formatted The term heading is formatted and put into codespan.

Inform about glossary terms which are no longer used in text

User Story

As a writer I want to know about glossary terms which could not be found and linked in text or which are no longer used in text. This will assist me in maintaining the glossary or finding out about missing aliases.

Use github schema URI in config example in README.md

Replace

{ 
  "$schema": "./node_modules/glossarify-md/conf.schema.json" 
}

with

{ 
  "$schema": "https://raw.githubusercontent.com/about-code/glossarify-md/v1.0.0/conf.schema.json" 
}

Publish v1.0.0 to npm

User Story

As a

• developer,
• technical writer,
• third-party toolchain provider

I want to be able to install glossarify-md from npm using npm install.

Support pandoc-style custom heading ids

User Story

As a writer I would like the system to use my custom pandoc-style heading IDs as heading anchors in order to be able to

• refer to sections using an identifier independent of the heading phrase
• use glossarify-md with markdown files written with and processed by other tools supporting custom heading ids (e.g. vuepress)

I would like the system to keep on auto generating heading IDs for headings without a custom heading id.

Enhancement Proposal

## My Heading with a Custom ID {#custom-id}

Lorem ipsum dolor...

## My Heading without a Custom ID

Lorem ipsum dolor...

should translate to

## [My Heading with a Custom ID](#custom-id)

Lorem ipsum dolor...

## [My Heading without a Custom ID](#my-heading-without-a-custom-id)

Lorem ipsum dolor...

in order to be able to refer to a section explicitely using a stable identifier

Lorem [ipsum](#custom-id) dolor...

Do also copy dot files to outDir

Actual Behavior

Hidden Folders with a preceding dot like .vuepress aren't copied from baseDir to outDir.

Expected Behavior

Hidden folders should be copied unless explicitely excluded via excludeFiles.

Only last occurrence of a shared term gets linked with all its definitions

Expected

A shared term is a term which has at least two definitions in two different glossaries. When such a term is mentioned in a paragraph the term should be linked with all its definitions. If the term is mentioned twice or more in a paragraph, any occurrence of the term should be linked to all its definitions.

Actual

Only the last occurrence of the term is linked with all its definitions. Prior occurrences in the same paragraph are only linked to the first definition found when processing glossaries.

Affected Versions

• <= v3.1.0

Limiting the number of glossary links

User Story

With a large body of terms being used to describe a domain the frequency of using terms from the body of terms increases with the level of details of the domain being described. So chapters describing very specific details of a domain tend to have paragraphs with many term occurrences. As a writer I would like to be able to limit the number of glossary links being created for better readability and less distraction.

As a writer I would like to be able to limit the number of links to only the first occurrence

• within a paragraph (paragraph is meant to be understood by the definition of the markdown syntax element paragraph)
• within a section (section is meant to be understood as the area between two headings (corresponding to the markdown syntax element heading)
• within a chapter (chapter is meant to be understood as the area between two headings (corresponding to the markdown syntax element heading with attribute depth 1)
• within a document (a markdown file)

v3.0.0: linkified headings don't play well with vuepress sidebar!

glossarify-md v3.0.0 introduced linkification of headings, to be able to generate an index file which links to sections where glossary terms have been found (option generateFiles.indexFile). Even though linkified headings are currently just required for index file generation they haven't been made optional intentionally. They free writers from writing the markup themeselves if they want to link to particular sections.

Unfortunately the markdown references syntax [Document][1] doesn't get parsed by vuepress when applied to headlines but is rather being displayed as [Document][1] just as if the markup were the actual headline text. Since heading linkification is one of the breaking changes introduced with v3.0.0 I do not want to change its default behavior and make it optional or disable it again since reverting that would require at least another two breaking changes (disabling/enabling) which I like to avoid, of course.

After all there is little value in switching to v3.0.0 for vuepress users since without heading linkification they can't use index-file generation, anyway. Therefore vuepress users: just keep on using v2.1.1 until a fix is available. Then install v3.0.x.. Sorry for the inconvenience.

Update CI test matrix to include newest non-LTS version of node

With glossarify-md v3.0.0 we announce a new node support matrix.

Node Version	glossarify-md compatibility & support status
Current	Tested (+ Supported). Should nodejs introduce breaking changes which turn out to affect glossarify-md severely then we may choose to step back from supporting current until it becomes the next LTS.
12.x LTS	Tested + Supported
10.x LTS	Tested + Supported
8.x LTS	Versions of glossarify-md >= 3.0.0 may continue to work with nodejs 8.x but may begin to use JS language features and APIs earliest available with nodejs 10.x LTS. Such changes might be introduced at any time including bugfix releases without classifying them as breaking changes.

---

The term support refers to supported technically and according to best-effort (see MIT license terms).

Support multiple term definitions

User Story

As a professional or scientifc writer I may have two or up to 10 different glossaries, each describing or defining the same term in a different context or language. When the term is found inside text I want to be able to jump to each of its ten definitions.

For example, if a term exists in multiple glossaries I want to have...

Variant 1 ... a comma-separated list of links following the term

This is my term (1), (2), ..., (10)
This is my *term* [(1)](../glossary1#term), [(2)](../glossary2#term), ..., [(10)](../glossary10#term)

• whether to use brackets or braces may be configurable.
• the dots are just to shorten things for the example

Variant 2 ... the term being linked to an index page from which I can access every definition

This is my term
This is my [term](../index#term)

index.md#term

term

1. This is the short description in glossary 1. [...] See glossary 1
2. This is another description in glossary 2. [...] See glossary 2
3. This is yet a third definition in glossary 3. [...] See glossary 3

Any of the two variants satisfies this requirement and may be implemented depending on effort.

4.0: Rethinking CLI-based configuration

The configuration schema grew complex and mapping it to individual CLI arguments makes the CLI difficult to understand and use. Rather than trying to map a complex configuration schema to command line options an easier interface were to provide only two options for merging a JSON string configuration with a file configuration:

For example:

glossarify-md 
  --config "./glossarify-md.conf.json"
  --shallow "{ 'glossaries': [{ 'termHint': '='}] }"

replaces the a glossaries: [...] array in the configuration file for that particular execution

glossarify-md 
  --config "./glossarify-md.conf.json"
  --deep "{ 'glossaries': [{ 'file': './glossary2.md', 'termHint': '+'}] }"

adds a new entry to glossaries: [...] array in the configuration file for that particular execution.

Combine listOfTables and listOfFigures with listOf anchor lists

User Story

As a user of glossarify-md I would like to generate a combined list of figures from generate.listOfFigures and generate.listOf lists with a class figure. I would like to generate a combined list of tables from generate.listOfTables and generate.listOf lists with a class of table. The combination allows for

• using both approaches of explict anchor declaration and implicit syntax analysis together
• easier migration from one approach to the other

Current Situation

• In glossarify-md v3.3 we introduced option generateFiles.listOfFigures to generate a list of figures based on analysis of Markdown image link syntax.

• In glossarify-md v3.5 we introduced option generateFiles.listOfTables to generate a list of tables based on analysis of Github Flavoured Markdown table syntax.

• In glossarify-md v3.6 we introduced a generic means of generating arbitrary lists of content elements based on analysis of HTML anchors <a> grouped by so called classes which are either denoted as a CSS class="" attribute or an id="class-" prefix.

Problem Statement

The latter is especially useful if images or graphics are generated on the fly either via scripts or interpreters, let's say of PlantUML code blocks instead of image links. However, up until now it is difficult to combine these different approaches. Users generating a list of figures with the v3.3 option can not get a generated figure added to the list unless they switch completely to the generic v3.6 anchor approach which forces them to annotate every markdown image link with an additional anchor tag.

Enhancement Proposal

Alternative 1

• generate.listOfFigures: { file: "...", title: "Figures" } should add images found via syntax analysis to a v3.6 anchor class figure, implicitely.
• generate.listOfTables: { file: "...", title: "Tables" } should add tables found via syntax analysis to a v3.6 anchor class table, implicitely.

Figures and tables found with the v3.3/v3.5 options can then be merged into lists generated with

• generate.listOf: [{ file: "...", class: "figure", title: "List of Figures"}]
• generate.listOf: [{ file: "...", class: "table", title: "List of Tables"}]

due to a conventional use of the classes figure and table.

Alternative 2

• generate.listOfFigures: { file: "...", title: "Figures", class="foo"} should be extended with a class attribute that is semantically equivalent to a v3.6 anchor class.
• generate.listOfTables: { file: "...", title: "Tables", class="bar" }`` should be extended with a class` attribute that is semantically equivalent to a v3.6 anchor class.

Figures and tables found with the v3.3/v3.5 options can then be merged into lists with the same but arbitrary anchor class

• generate.listOf: [{ file: "...", class: "foo", title: "List of Images"}]
• generate.listOf: [{ file: "...", class: "bar", title: "List of Tables"}].

In both Alternatives

Since both options allow for title attribute the generic listOf title takes precedence over the listOfFigures title if both are present. Otherwise the one being present is being taken and if none is present a common default is used.

Aliases: Trailing comma causes infinite loop with out-of-memory failure

Reproduction

Aliases with trailing comma

## My Term
<!-- Aliases: term 1, term 2, -->

Affected versions

• v1.0
• v1.1
• v1.1.1

Option to let user define position of term hint

User Story

Currently a term hint always follows the term link.

• As a writer I want to have at least a choice whether to prepend or append the term hint.
• As an advanced writer I want to be able to embed the term into a custom format string.

--force flag not working in v4.0.0

When reading and writing back to the same folder, the --force flag is required. Passing this at the end of the command does not seem to work in v4.0.0 (it worked in v3.6.5), instead, an error is output stating that the flag is required and then the tool aborts.

glossarify-md.conf.json:

{
  "$schema": "./node_modules/glossarify-md/conf.schema.json",
  "baseDir": "./",
  "outDir": "./",
  "glossaries": [
     { "file": "./GLOSSARY.md" }
  ],
  "ignoreCase": true,
  "includeFiles": ["./docs/*/*.md"],
  "excludeFiles": ["node_modules"],
  "linking": "absolute"
}

Output:

+ npx glossarify-md --config ./glossarify-md.conf.json --baseUrl https://github.com/my-org/my-repo/blob/branch_name --force
npx: installed 129 in 5.808s
┌──────────────────────────┐
│   glossarify-md v4.0.0   │
└──────────────────────────┘

☛ Reading from: /github/workspace
☛ Writing to:   /github/workspace

⚠ Warning: --baseDir and --outDir resolve to the same directory.
Such a config is going to overwrite input files in --baseDir.
Choose a different --outDir or change config provided via --config.
Use --force if you want to proceed with current settings.
See --help for details.

ABORTED.

Dangling anchor links with German Umlauts when used with vuepress

Reproduction

When using glossarify-md with vuepress a glossary term

## Der Tod und das Mädchen
Classic composition by Franz Schubert (The Death and the Maiden).

will be correctly found in text but the link in the text doesn't link to the glossary term.

Linkification in embedded HTML

Bug

As a user I want to be sure that the link target is the one indicated by the link label. As a user I do not want to have links indicating a glossary link where the actual link target is something else. This issue adresses the following warning in README.md:

Important: As of now, we can't prevent text between the opening and closing angle brackets of an HTML link to be linkified. In a markdown syntax tree something like term is represented as distinct HTML nodes with arbitrary complex markdown nodes in between. Therefore a term found between those HTML tags currently results in

<a href="">[term][1]</a>

[1] ./glossary.md#term

Acceptance Criteria

• Text inside HTML markup must no longer be linkified. This will be a BREAKING CHANGE.
• The warning in README.md should be removed

Upgrade unified

• Changelog [email protected]