diff --git a/.eslintrc.json b/.eslintrc.json index 49c9c26c..47fb6080 100644 --- a/.eslintrc.json +++ b/.eslintrc.json @@ -17,7 +17,7 @@ "rules": { "semi": [ "error", "always" ] ,"quotes": [ "error", "double" ] - ,"indent": [ "error", 4 ] + ,"indent": [ "error", 4, { "SwitchCase": 1 } ] ,"dot-location": ["error", "property"] ,"dot-notation": ["error"] ,"linebreak-style": [ "error", "unix" ] diff --git a/README.md b/README.md index 687bba86..ea5d8a48 100644 --- a/README.md +++ b/README.md @@ -3,29 +3,27 @@ ![Tests (Functional)](https://github.com/about-code/glossarify-md/workflows/Tests%20\(Functional\)/badge.svg) ![Nightly Tests (Latest Dependencies)](https://github.com/about-code/glossarify-md/workflows/Tests%20\(with%20latest%20deps\)/badge.svg) -[glossarify-md] is a command line tool to help Markdown writers with +[CommonMark]: https://www.commonmark.org -- **Cross-Linking** (primary use case): autolink terms to some definition in a glossary -- **Indexes**: generate indexes from glossary terms and navigate to where they were mentioned -- **Lists**: generate arbitrary lists such as *List of Tables*, *List of Figures*, *List of Listings*, *List of Definitions*, *List of Formulas*, and so forth... +[doc-book-index]: https://github.com/about-code/glossarify-md/blob/master/doc/gen-book-index.md -[vuepress] users might be interested in learning [how to use the tool with vuepress][doc-vuepress]. +[doc-config]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md -[doc-paths-and-urls]: https://github.com/about-code/glossarify-md/blob/master/doc/paths-and-urls.md +[doc-cross-linking]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md -[doc-vocabulary-uris]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md +[doc-extended]: https://github.com/about-code/glossarify-md/blob/master/doc/README.md -[doc-skos-interop]: https://github.com/about-code/glossarify-md/blob/master/doc/skos-interop.md +[doc-options]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md -[doc-vuepress]: https://github.com/about-code/glossarify-md/blob/master/doc/use-with-vuepress.md +[doc-paths-and-urls]: https://github.com/about-code/glossarify-md/blob/master/doc/paths-and-urls.md [doc-syntax-extensions]: https://github.com/about-code/glossarify-md/blob/master/doc/markdown-syntax-extensions.md -[doc-conceptual-layers]: https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md +[doc-term-attributes]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md -[doc-config]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md +[doc-vocabulary-uris]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md -[CommonMark]: https://www.commonmark.org +[doc-vuepress]: https://github.com/about-code/glossarify-md/blob/master/doc/use-with-vuepress.md [GFM]: https://github.github.com/gfm/ @@ -33,55 +31,41 @@ [glossarify-md]: https://github.com/about-code/glossarify-md -[jsonld]: https://npmjs.com/package/jsonld +[Hugo]: https://gohugo.io [link reference definitions]: https://spec.commonmark.org/0.30/#link-reference-definition -[mdast]: https://github.com/syntax-tree/mdast - -[micromark]: https://github.com/micromark/ - [pandoc]: https://pandoc.org [pandoc-heading-ids]: https://pandoc.org/MANUAL.html#heading-identifiers -[remark]: https://github.com/remarkjs/remark - -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter - -[remark-plugins]: https://github.com/remarkjs/awesome-remark - -[unified]: https://unifiedjs.com - [unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md [vuepress]: https://vuepress.vuejs.org [YAML]: https://yaml.org +[glossarify-md] is a command line tool to help Markdown writers with + +- **Cross-Linking** (primary use case): autolink terms to some definition in a glossary +- **Indexes**: generate indexes from glossary terms and navigate to where they were mentioned +- **Lists**: generate arbitrary lists such as *List of Tables*, *List of Figures*, *List of Listings*, *List of Definitions*, *List of Formulas*, and so forth... + ## Table of Contents - [Prerequisites](#prerequisites) - [Install](#install) - [Configuration](#configuration) - [Sample](#sample) -- [What's not Linked](#whats-not-linked) + - [Input](#input) + - [Output](#output) +- [What's not being linkified](#whats-not-being-linkified) - [Aliases and Synonyms](#aliases-and-synonyms) - [Term Hints](#term-hints) - [Multiple Glossaries](#multiple-glossaries) - [Sorting Glossaries](#sorting-glossaries) -- [Cross Linking](#cross-linking) - - [Term-Based Auto-Linking](#term-based-auto-linking) - - [Identifier-based Cross-Linking](#identifier-based-cross-linking) -- [Generating Files](#generating-files) - - [Book Index](#book-index) - - [Lists](#lists) - - [List of Figures](#list-of-figures) - - [List of Tables](#list-of-tables) - - [Lists from Regular Expressions](#lists-from-regular-expressions) -- [Structured Export and Import](#structured-export-and-import) +- [Advanced Topics](#advanced-topics) - [Node Support Matrix](#node-support-matrix) -- [Options](#options) - [Special Thanks go to](#special-thanks-go-to) - [License](#license) @@ -91,16 +75,7 @@ ## Install -#### Option 1: Install *globally*, init config and run: - -``` -npm install -g glossarify-md - -glossarify-md --init --new -glossarify-md --config ./glossarify-md.conf.json -``` - -#### Option 2 (recommended): Install *locally*, init config and run: +#### Option 1: Install *locally*, init, configure, run (recommended): ``` cd ./your-project @@ -110,13 +85,9 @@ npx glossarify-md --init --new --local npx glossarify-md --config ./glossarify-md.conf.json ``` -**Optionally:** You might want to set up a shortcut... - -``` -npm run glossarify -``` +> **ⓘ Since 6.3.0** glossarify-md supports a `--watch` mode. -... by adding a run script to your `package.json`: +When installing locally you might want to set up a shortcut by adding a run script to your `package.json`: ```json { @@ -126,11 +97,36 @@ npm run glossarify } ``` -> **ⓘ Since 6.3.0** glossarify-md supports a `--watch` mode. +Next time you're able to use: + +``` +npm run glossarify +``` + +#### Option 2: Install *globally*, init, configure, run: + +``` +npm install -g glossarify-md + +glossarify-md --init --new +glossarify-md --config ./glossarify-md.conf.json +``` ## Configuration -If you've followed the installation instructions you are already set up for a quick start. For customizing your configuration **[see here][doc-config]**. +By following the installation instructions you should be set up with a minimal configuration: + +*Minimal Configuration* + +```json +{ + "$schema": "./node_modules/glossarify-md/conf/v5/schema.json", + "baseDir": "./docs", + "outDir": "../docs-glossarified" +} +``` + +**[More configuration options here][doc-config]**. ## Sample @@ -153,9 +149,9 @@ ${root} `- glossarify-md.conf.json ``` -**Input** +### Input -Your original glossary is a file +Your original glossary is a file with *term definitions* *docs/glossary.md* @@ -167,12 +163,12 @@ Your original glossary is a file A glossary term has a short description. The full description contains both sentences. ``` -Your document files may just use the term *Term* anywhere in text: +The term *Term* may occurs anywhere in the rest of your document files: *./docs/pages/page1.md...* ```md -# Demo +# Document This is a text which uses a glossary Term to describe something. ``` @@ -183,21 +179,21 @@ Then run [glossarify-md] with a [glossarify-md.conf.json](#configuration): npx glossarify-md --config ./glossarify-md.conf.json ``` -**Output Results** +### Output Augmented versions of the source files have been written to the output directory: -*./docs-glossarified/pages/page1.md* +*Source: ./docs-glossarified/pages/page1.md* ```md -# [Demo](#demo) +# [Document](#document) This is a text which uses a glossary [Term][1] to describe something. [1]: ../glossary.md#term "A glossary term has a short description." ``` -*Rendered as HTML:* +*When rendered to HTML:* > ## [Demo](#demo) > @@ -205,9 +201,7 @@ This is a text which uses a glossary [Term][1] to describe something. > > [1]: #term "A glossary term has a short description." -Headings in glossary files have got an anchor ID and have been made linkable: - -*./docs-glossarified/glossary.md*: +*Source: ./docs-glossarified/glossary.md*: ```md # [Glossary](#glossary) @@ -217,7 +211,7 @@ Headings in glossary files have got an anchor ID and have been made linkable: A glossary term has a short description. The full description contains both sentences. ``` -*Rendered as HTML*: +*When rendered to HTML*: > ## [Glossary](#glossary) > @@ -225,19 +219,18 @@ A glossary term has a short description. The full description contains both sent > > A glossary term has a short description. The full description contains both sentences. -## What's not Linked +## What's not being linkified -Some syntactic positions of a term occurrence are **excluded** from being linked to the glossary. Terms are not linkified when part of: +Some syntactic positions of a term occurrence are **excluded** from being linked to the glossary, for example when the term occurs in: +- HTML `text` - Headlines `#` - (Markdown) links `[]()` - Preformatted blocks ` ```, ~~~ ` - Blockquotes `>` -- HTML `text` + - 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. -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. - -> **ⓘ Tip:** Wrap a word into some pseudo HTML tag like e.g. `word` to mark a word for exclusion from [term-based auto-linking][cross-linking]. +> **ⓘ Tip:** Wrap a word into some pseudo HTML tag like e.g. `word` to mark a word for exclusion from [term-based auto-linking][doc-cross-linking]. ## Aliases and Synonyms @@ -245,9 +238,7 @@ Blockquotes are excluded based on the premise that a quoted entity may not share [aliases]: #aliases-and-synonyms -[term-attributes]: #aliases-and-synonyms - -Aliases can be added by what we call *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: +Aliases 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: *glossary.md with a term attribute `aliases`:* @@ -269,7 +260,7 @@ In the output files aliases will be linked to their related term: [Cats](./glossary.md#cat) and kitten almost hidden spotting mouses in their houses. [Andreas Martin] ``` -> **ⓘ Note:** [YAML] syntax is *case-sensitive* as well as *sensitive to tabs and whitespaces*. In general term attributes will be lowercase. You may find that an uppercase `Aliases: ` term attribute works as well. This is going to be the only attribute for which an uppercase name remains supported *for backwards compatibility*. +> **ⓘ Note:** [YAML] syntax is *case-sensitive* as well as *sensitive to tabs and whitespaces*. In general term attributes will be lowercase. That's all you need to know for a quick start. Continue reading to learn about additional features. @@ -285,13 +276,11 @@ That's all you need to know for a quick start. Continue reading to learn about a Glossaries 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. -> **ⓘ Since v5.0.0**: `file` can also be used with a [glob] pattern. More see [Cross-Linking]. - ## Multiple Glossaries [multiple-glossaries]: #multiple-glossaries -Sometimes you might whish to have multiple glossaries. For example as a Requirements Engineer you may not just have a glossary of business terms but also a requirements catalogue: +Sometimes you might whish to have multiple glossaries: *glossarify-md.conf.json* @@ -312,7 +301,9 @@ Sometimes you might whish to have multiple glossaries. For example as a Requirem ``` -By adding *requirements.md* to the list of glossaries every use of *REQ-1* or *REQ-2* in documents gets linked to the requirements glossary. To navigate the opposite direction from a requirement to sections where those got mentioned you can generate a [Book Index](#book-index). +By adding *requirements.md* to the list of glossaries every use of *REQ-1* or *REQ-2* in documents gets linked to the requirements glossary. To navigate the opposite direction from a requirement to sections where those got mentioned you can generate a [Book Index][doc-book-index]. + +**Since v5.0.0** `file` can also be used with a [glob] pattern. This way each markdown file matching the pattern is considered a glossary. More see [Cross-Linking][doc-cross-linking]. ## Sorting Glossaries @@ -337,412 +328,16 @@ Internally, glossarify-md uses `Intl.Collator` and falls back to `String.localeC } ``` -The 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): - -## Cross Linking - -[cross-linking]: #cross-linking - -> **ⓘ Since: v5.0.0** - -### Term-Based Auto-Linking - -*Term-based auto-linking* is what we've seen so far. It is to assume headings in markdown files called *glossaries* are *terms* that whenever being mentioned in text are being turned into a link to the glossary section where they have been defined as a term. - -**Since v5.0.0** we've added a few features which let us evolve that principle into a more generic means of cross-linking beginning with support for [glob] patterns in `glossaries.file`. For example with ... - -```json -"glossaries": [ - { "file": "./**/*.md"} -] -``` - -... you can turn any `*.md` file being processed into a "glossary". Now *all* document headings are considered terms. Mentioning the heading or an [alias] alike turns the phrase into a link to that section. - -> **ⓘ Too many links?** -> -> What might happen with *globs* is, that you might feel that *too many links* are being generated disturbing the reading experience. If this is an issue for you explore options like [`linking.mentions`](#linkingmentions), [`linking.headingDepths`](#linkingheadingdepths) or [`linking.limit*`](#linkinglimitbyalternatives) options. - -> **ⓘ Note:** When there are multiple `glossaries: []` entries with a `{ file: ... }` glob or path and a given file matches more than one entry then `glossaries` options of the entry latest in the array will apply. Though avoid too many glob patterns or patterns whose file sets overlap as the effects on the output get increasingly hard to understand, otherwise. - -### Identifier-based Cross-Linking - -If the same section heading exists more than once then you might want to link to one heading in particular. While you should consider using an [alias] to make use of term-based auto-linking, there might be situations where you whish to have manually declared links. - -**Since v5.0.0** we've added support for manual cross-linking through [pandoc's concept of heading ids][pandoc-heading-ids]. These allow you to assign identifiers which are more stable for referencing than auto-generated IDs derived from the heading phrase (slugs). - -> **ⓘ Note:** Pandoc's identifier syntax is not standardized in [CommonMark]. - -[Sample]: document `./pages/page1.md` declares a heading - -*/pages/page1.md* - -```md -## User Story {#s-241} -``` - -with heading-id `#s-241`. **Given that `#s-241` is *unique* across all documents** you can use it as a link reference: - -```md -[any phrase](#s-241) -``` - -In any file being processed [glossarify-md] will resolve the actual path to the definition: - -*/README.md* - -``` -[any phrase](./pages/page1.md#s-241) -``` - -*/pages/page2.md* - -``` -[any phrase](./page1.md#s-241) -``` - -## Generating Files - -### Book Index - -*glossarify-md.conf.json* - -```json -"generateFiles": { - "indexFile": { - "file": "./book-index.md", - "title": "Book Index" - } -} -``` - -This option will generate a single book index file `./book-index.md` with glossary terms and links to book sections in which they have been mentioned. By default items will be grouped *by section of occurrence* using the section heading as a group title. You can disable or affect granularity of section-based grouping using: - -```json -"indexing": { - "groupByHeadingDepth": 0 -} -``` - -> **ⓘ Note**: The `groupByHeadingDepth` option also affects grouping of list items in [Lists](#lists). - -Let's assume you have multiple glossaries and you want to create separate book indexes from terms of those glossaries. **Since v5.1.0** you can use `indexFiles` (plural) like this: - -```json -"generateFiles": { - "indexFiles": [{ - "title": "Book Index for Glossary 1", - "file": "./book-index-1.md", - "glossary": "./glossary-1.md" - },{ - "title": "Book Index for Glossary 2", - "file": "./book-index-2.md", - "glossary": "./glossary-2.md" - }] -} -``` - -> **ⓘ Note:** If you plan on translating markdown to HTML, e.g. with [vuepress](https://vuepress.vuejs.org), be aware that a file `index.md` will translate to `index.html` which is typically reserved for the default HTML file served under a domain. We recommend you choosing another name. - -### Lists - -You can generate **arbitrary lists from HTML elements with an `id` attribute** and an element *classifier* to compile similar elements into the same list. - - -*Example: Markdown document with a video element* - -```md -More details see our video tutorial: - - -``` - -Then to generate a *List of Videos* from all elements of `class="video"` add to your *glossarify-md.conf.json*: - -```json -"generateFiles": { - "listOf": [{ - "class": "video", - "title": "List of Videos", - "file": "./videos.md" - }] -} -``` - -After running glossarify-md there will be a file: - -*docs-glossarified/videos.md (generated)* - -> ## List of Videos -> -> - [Tutorial Part 1](#video-tutorial-part-1) - -You can **type less** when prefixing ids with your list classifier: - -```md - -``` - -Without a `title` attribute the tool attempts to derive a list item label from an elements inner text content: - -```md - -``` - -Use *invisible* HTML anchors to generate lists from and navigate to text content: - -```md - -This is not a video tutorial but a textual tutorial. The body of text can be navigated to from a List of Tutorials and uses the classifier *tutorial*. -``` - -> **ⓘ Note:** If you find the browser not scrolling correctly when navigating lists on GitHub, please read [Addendum: Lists in GitHub Repos](https://github.com/about-code/glossarify-md/blob/master/doc/lists-on-github.md). - - - -### List of Figures - -So far we used [`listOf`](#lists) to generate a list from *HTML elements* in Markdown. Writing HTML can be annoying, particularly if there is handier Markdown syntax for the elements to be listed. This is where -`listOfFigures` and [`listOfTables`](#list-of-tables) fit in. It is a shortcut which makes [glossarify-md] generate the HTML anchor itself from Markdown's image syntax: - -```md -![List item Label](./figure.png) -``` - -Then you may only need to use HTML for dynamically rendered figures, e.g. a [PlantUML](https://plantuml.com) diagram: - -````md -
Dynamically Rendered Diagram
- -```plantuml -@startuml -... your PlantUML diagram code ... -@enduml -``` -```` - -To compile both figures into the same list one way to configure [glossarify-md] is to declare a `listOf` class *figure* (for HTML elements) and tell `listOfFigures` (for `![]()` images) to use the same classifier *figure*: - -*glossarify-md.conf.json* (since v5.0.0) - -```json -"generateFiles": { - "listOf": [{ - "class": "figure", - "title": "List of Figures", - "file": "./figures.md" - }], - "listOfFigures": { - "class": "figure" - } -} -``` - -This configuration which would allow you to also choose a shorter classifier like *fig* is the default, though. Therefore, if you are fine with ***figure* as the default classifier** you can omit `listOf` and just use: - -*glossarify-md.conf.json* - -```json -"generateFiles": { - "listOfFigures": { - "title": "List of Figures", - "file": "./figures.md" - } -} -``` - -### List of Tables - -`listOfTables` like [`listOfFigures`](#list-of-figures) is a shortcut alternative to HTML anchors with a default [`listOf`](#lists) classifier ***table***: - -*glossarify-md.conf.json* - -```json -"generateFiles": { - "listOfTables": { - "title": "Tables", - "file": "./tables.md" - } -} -``` - -In contrast to images Markdown tables have no notion of a table caption. To render a list item for a table [glossarify-md] tries to infer a list item label. - -One such inference looks at the **paragraph preceding the table**. If it **ends with an *emphasized* phrase** and the phrase itself is **terminated by a colon** then the tool uses that phrase as the item label: - - - -```md -[...] which we can see from the *table of average prices by article category:* - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -But the phrase could also be it's own distinct paragraph: - -```md -[...] which we can see from the average price by article category. - -*Average prices by category:* - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -**Since v3.4.0** there has also been support for *invisble* table captions using *HTML comment syntax*: - -```md - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -The result for the tables above will be: - -> ## List of Tables -> -> - [Table of average prices by article category](#table-of-average-prices-by-article-category) -> - [Average prices by category](#average-prices-by-category) -> - [Average Prices by Article Category](#avg-prices) - -**Since v5.0.0** and the introduction of `listOf` all the previous examples will make [glossarify-md] annotate the table with an HTML anchor. So while not recommended due to verbosity, you could of course also just add an HTML anchor yourself, like described in [`listOf`](#lists): - -```md - - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -> **ⓘ Note:** If [glossarify-md] can't find a list item label by any of the above means it will fall back to rendering a list item -> -> 1. using the table headers separated by comma, -> 1. or if no headers, using the closest section heading -> 1. or if no section heading, using the file name. - - - -### Lists from Regular Expressions - -**Since v5.2.0** you can use `listOf` with a regular expression pattern. Like `listOfFigures` and `listOfTables` it is meant to be a shortcut to save you from annotating Markdown with HTML elements yourself. - -Let's assume you are writing a book with tasks to be accomplished by your readers. You would like to compile a *List of Tasks* in that book. You decided to use a conventional pattern which prefixes tasks with a phrase **Task:** and ends them with an exclamation mark *!* - -*Document.md* - -```md -Some text [...] - -**Task:** Clap your hands! -``` - -You can then generate a *List of Tasks* with a configuration like this: - -```md -{ - "generateFiles": { - "listOf": [ - { - "class": "task", - "title": "Tasks in this Book", - "file": "./list-of-tasks.md", - "pattern": "Task: ([a-zA-Z0-9].*)!" - } - ] - } -} -``` - -If the regular expression (RegExp) matches text in a paragraph, then *the paragraph* will be annotated with an anchor for `listOf`. Our RegExp has a Capture Group in braces `()`. Text matching the group pattern will become the list item label, so *Clap your hands* in the example because `Task:` and exclamation mark `!` are not part of the group. - -> **ⓘ When to consider "markdown syntax" in the RegExp**: -> -> You may noticed that the RegExp above doesn't assume *Task:* to be written between "bold" star markers `**`. The expression won't be matched against the input *you* wrote but against *plain text* cleaned from symbols contributing to [CommonMark] or [GFM] syntax. -> -> In case you use another Markdown flavor see our addendum on [Markdown Syntax Extensions][doc-syntax-extensions]. Without a proper plug-in its syntactical elements are likely considered plain text, too. Then they need to be taken care of in the RegExp to make it match. - -## Structured Export and Import - -[doc-export-import]: #structured-export-and-import - -[SKOS]: https://w3.org/skos - -**Since v6.0.0** glossary terms can be exported to a structured JSON format (file extension `.json`). When [jsonld] is installed alongside glossarify-md then terms can also be exported to RDF N-Quads (file extension `.nq`). - -*glossarify-md.conf.json* (generates ./glossary.json) - -```json -{ - "glossaries": [{ - "uri": "http://basic.org/vocabulary/#", - "file": "./glossary.md", - "export": { - "file": "./glossary.json" - } - }] -} -``` - -Declare a glossary `uri` when exporting. It will make [glossarify-md] assign each term a *uniform resource identifier* by combining the glossary's `uri` with a term's book-internal identifier (see [`headingIdAlgorithm`][headingIdAlgorithm]). Note that URIs are not required to resolve to some web page but *can* do so. More on the idea behind URIs read [here][doc-vocabulary-uris]. You can import terms the same way using `import` instead. - -*glossarify-md.conf.json* (generates ./glossary.md): - -```json -{ - "glossaries": [{ - "uri": "http://basic.org/vocabulary/#", - "file": "./glossary.md", - "import": { - "file": "./glossary.json" - } - }] -} -``` +The `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): -> ⚠ **Important:** [glossarify-md] is able to import JSON glossaries from a remote location using `https`. While it will try to remove any Markdown and HTML from imported term definitions using [strip-markdown](https://npmjs.com/package/strip-markdown) it can only do so after `JSON.parse()`. As a rule of thumb never import from untrusted sources and assume that any files from a remote location could enable a remote entity to embed malicious code into outputs or execute such code in the runtime context of [glossarify-md]. Consider importing files statically after review. +## [Advanced Topics][doc-extended] -Advanced topics on importing and exporting can be found [here](https://github.com/about-code/glossarify-md/blob/master/doc/skos-interop.md). +- Importing and exporting terms +- Generating files, such as a book index, lists of figures, etc. +- Cross-Linking more than just terms +- Using glossarify-md with other tools, like [vuepress], [pandoc] or [Hugo] +- Dealing with non-standard Markdown Syntax via Plug-ins (e.g Frontmatter) +- [...and more][doc-extended] ## Node Support Matrix @@ -756,415 +351,12 @@ The term *support* refers to *runs on the given platform* and is subject to the | 12 LTS | v3, v4, v5 | | | 10 LTS | v2, v3, v4 | | -## Options - -[Options]: #options - -#### `baseDir` - -- **Range:** `string` - -Path to directory where to search for the glossary and markdown files. All paths in a config file except for `$schema` will be relative to *baseDir*. *baseDir* itself and `$schema` are relative to the location of the config file. - -#### `excludeFiles` - -- **Range:** `string[]` - -Paths or Glob-Patterns of files to exclude. Excluded files will be excluded from being copied to `outDir` where they would be processed. Use [`keepRawFiles`](#keeprawfiles) if you want to have them copied to `outDir` but *ignored* by glossarify-md. - -#### `generateFiles` - -- **Range:** `Object` - -``` -{ - indexFile: {}, - listOf: [], - listOfFigures: {}, - listOfTables: {} -} -``` - -#### `generateFiles.indexFile` - -[doc-config-indexFile]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-generatefiles-properties-indexfile.md - -- **Range:** `{file: string, [title: string], [hideDeepLinks: boolean]}` ([details][doc-config-indexFile]) -- **Since:** v3.0.0 - -Generates an index of glossary terms with links to files in which they have been mentioned. - -#### `generateFiles.indexFiles` - -[doc-config-indexFiles]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-generatefiles-properties-indexfiles-items.md - -- **Range:** `Array<{file: string, glossary: string, [title: string], [hideDeepLinks: boolean]}>` ([details][doc-config-indexFiles]) -- **Since:** v3.0.0 - -Similar to `indexFile` but allows for generating multiple index files, e.g. one per glossary. - -#### `generateFiles.listOf` - -[doc-config-listOf]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-generatefiles-properties-listof-items.md - -- **Range:** `Array<{class: string, file: string, [title: string]}>` ([details][doc-config-listof]) -- **Since:** v3.5.0 - -If available, generates a list from HTML anchors exposing the configured `class` attribute. - -#### `generateFiles.listOfFigures` - -- **Range:** `{file: string, [title: string, class: string]}` -- **Since:** v3.3.0 - -Generates a list of figures with links to sections where the figures have been mentioned. - -#### `generateFiles.listOfTables` - -- **Range:** `{file: string, [title: string, class: string]}` -- **Since:** v3.4.0 - -Generates a list of tables. - -#### `glossaries` - -- **Range:** `Array` - -``` -[ - { - file: string, - termHint: string, - sort: string], - uri: string, - linkUris: boolean, - showUris: boolean|string, - import: {}, - export: {}, - } -] -``` - -- **Default:** `[{ "file": "./glossary.md", "termHint": "" }]` - -A list of glossary configuations, each with a path to the glossary file. Every -glossary may have an optional *termHint*. A *termHint* is a symbol character -being appended to term occurrences in order to indicate which glossary or -category a term belongs to. A term hint may be any UTF-8 character or character -sequence. If you would like to have the glossary sorted provide a *sort* direction -`"asc"` or `"desc"`. - -#### `glossaries[].export` - -[doc-config-export]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-glossaryfile-properties-export-oneof-0.md - -- **Range:** `{ file: string [, context: string]} | Array<{ file: string [, context: string]}>` ([details][doc-config-export]) -- **Since:** v6.0.0 - -Export markdown terms in a structured JSON format. More read [here][doc-export-import]. - -#### `glossaries[].import` - -[doc-config-import]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-glossaryfile-properties-import.md - -- **Range:** `{ file: string [, context: string]}` ([details][doc-config-import]) -- **Since:** v6.0.0 - -Import terms from a structured JSON format and generate a markdown glossary from it. For an example see [here][doc-export-import]. - -#### `glossaries[].linkUris` - -- **Range:** `boolean` -- **Default:** `false` -- **Since:** v6.0.0 - -When `true`, occurrences of glossary terms found in text will no longer be linked with the markdown glossary file but with an external definition on the web using a term's URI. The given glossary file will serve as a data source for a link title providing a short tooltip and may still be found from [indexFiles](#generatefilesindexfiles). - -#### `glossaries[].showUris` - -- **Range:** `boolean|string` -- **Default:** `false` -- **Since:** v6.0.0 - -When being `true` or being a template string with a placeholder `${uri}` then render term URIs in glossaries generated from [imported][doc-export-import] terms. - -#### `glossaries[].uri` - -See also [Vocabulary URIs][doc-vocabulary-uris]. - -#### `ignoreCase` - -- **Range:** `boolean` - -When true any occurrence of a term will be linked no matter how it was spelled. - -#### `includeFiles` - -- **Range:** `string[]` - -Paths or Glob-Patterns for files to include. Default: `.` (includes all Markdown files within the current directory and its subdirectories). See also [`excludeFiles`](#excludefiles) and ([`keepRawFiles`](#keeprawfiles)). - -#### `indexing` - -- **Range:** `Object` - -``` -{ - headingDepths: number[], - groupByHeadingDepth: number, -} -``` - -#### `indexing.groupByHeadingDepth` - -- **Range:** `number` in \[1-6] -- **Default:** 6 -- **Since:** v3.4.0 - -This option affects outputs generated with `generateFiles`. By default when -indexing terms and markdown elements they are being grouped by the heading of -the section they've been found in. In larger books with many sections and -subsections this can lead to Index files or *Tables of X* with a lot of group -headings (many representing sub- and subsubsections). Yet often it's enough for -an Index to only list the chapter or higher-level sections where some term or -element has been found in. This option allows to set the depth by which -elements shall be grouped where `1` refers to chapters (`#` headings). - -#### `indexing.headingDepths` - -- **Range:** `number[]` in 1-6 -- **Default:** `[1,2,3,4,5,6]` -- **Since:** v5.0.0 - -An array with items in a range of 1-6 denoting the depths of headings that should be indexed. Excluding some headings from indexing is mostly a performance optimization, only. You can just remove the option from your config or stick with defaults. Change defaults only if you are sure that you do not want to have cross-document links onto headings at a particular depth, no matter whether the link was created automatically or written manually. Default is `[1,2,3,4,5,6]`. - -The relation to [`linking.headingDepths`](#linkingheadingdepths) is that *this* is about *knowing the link targets* whereas the latter is about *creating links automatically ...based on knowledge about link targets*. Yet, indexing of headings is further required for existing (cross-)links like `[foo](#heading-id)` and resolving the path to where a heading with such id was declared, so for example `[foo](../document.md#heading-id)`. - -#### `i18n` - -- **Range**: `Object` - -``` -{ - locale: string, - [localeMatcher: string], - [caseFirst: string], - [ignorePunctuation: boolean], - [numeric: boolean], - [sensitivity: string], - [usage: string] -}` -``` - -Locale options to control [sorting](#sorting-glossaries). See [`Intl.Collator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator/Collator). - -#### `keepRawFiles` - -- **Range:** `string[]` - -Paths or Glob-Patterns for Markdown files to copy to `outDir` but keep there as they are without -glossarifying and linking. Non-markdown files won't be processed anyways, so no need to add those. - -#### `linking` - -- **Range:** `Object` - -``` -{ - baseUrl: string, - byReferenceDefinition: boolean, - paths: "relative" | "absolute", - pathComponents: ["path", "file", "ext"], - pathRewrites: {}, - mentions: "all" | "first-in-paragraph", - headingAsLink: boolean, - headingDepths: number[], - headingIdAlgorithm: "github" | "md5" | "md5-7" | "sha256" | "sha256-7", - headingIdPandoc: boolean, - limitByAlternatives: number - limitByTermOrigin: ["self", "parent", "sibling", "child", "parent-sibling"] -} -``` - -#### `linking.baseUrl` - -- **Range:** `string` - -URL to prepend to links. Only effective with `linking.paths: "absolute"`. In most situations, e.g. when hosting markdown files in a repository or processing markdown files with an HTML converter omitting a pre-defined `baseUrl` and using `linking.paths: "relative"` is likely to work better. - -#### `linking.byReferenceDefinition` - -- **Range:** `boolean` -- **Default:** `true`, -- **Since:** v6.0.0 - -Whether to convert inline-links to [link reference definitions] (size-efficient). - -#### `linking.headingAsLink` - -- **Range:** `boolean` -- **Default:** `true` -- **Since:** v6.0.0 - -Whether to linkify headings. Note that some Markdown-to-HTML renderers need headings to be linkified in order to be rendered URL-addressable and navigable. Others like [pandoc] don't need linkified headings but special syntax. - -See also: - -- [`linking.headingIdPandoc`](#linkingheadingidpandoc) - -#### `linking.headingDepths` - -- **Range:** `number[]` in 1-6 -- **Default:** `[2,3,4,5,6]` -- **Since:** v5.0.0 - -Use this option to select markdown heading depths which should be considered terms or sections for cross-linking. For example, to only consider headings `## text` at depth 2 or `### text` at depth 3 but not at depths 1 and 4-6 provide an array `[2,3]` - -> **ⓘ Note:** Headings at the given depths must be indexed. So they must be in the set of [`indexing.headingDepths`](#indexingheadingdepths). - -#### `linking.headingIdAlgorithm` - -[headingIdAlgorithm]: #linkingheadingidalgorithm - -- **Range:** `"github" | "md5" | "md5-7" | "sha256" |"sha256-7"` -- **Default:** `"github"` -- **Since:** v6.0.0 - -Algorithm to use for generating heading identifiers used as `#` URL-fragment ("slugs"). Option value `"github"` will only guarantee *uniqueness per file* whereas `md5` and `sha256` options will generate a hash *unique in the fileset*. The hash value will depend on - -``` -hash ( - glossary file path, - glossary file name without file extension, - glossary uri, - github-slugger(term), - baseUrl -) -``` - -where `baseUrl` will be used only if there's no glossary uri. The `*-7` hashsum variants truncate a hash to at most 7 symbols which are still unlikely to collide in normal books. - -#### `linking.headingIdPandoc` - -- **Range:** `boolean` -- **Default:** false -- **Since:** v6.0.0 - -Since v5 there has been support for *parsing* pandoc-style heading IDs from input markdown. In v6 we added support for *writing* pandoc-style `{#id}` identifiers to output markdown to facilitate postprocessing with [pandoc]. - -> **ⓘ Note:** Pandoc's identifier syntax is not standardized in [CommonMark]. - -See also - -- [`linking.headingIdAlgorithm`](#linkingheadingidalgorithm) -- [`linking.paths`](#linkingpaths) - -#### `linking.limitByAlternatives` - -- **Range:** `number[]` in -95 - +95 -- **Default:** 95 -- **Since:** v5.0.0 - -Control how a term occurrence is linkified if there are *multiple definitions* of a term: - -- **positive value**: the system *creates links to alternative definitions but no more than `x` links*. -- **negative value**: the system does *not create a term-link at all once there are more than `x` alternative definitions* of a term or heading. -- **zero**: create a link but to a single out of all definitions, only - -#### `linking.limitByTermOrigin` - -- **Range:** `string[]` in `["self", "parent", "sibling", "child", "parent-sibling"]` -- **Default:** `[]` -- **Since:** v6.1.0 - -Limits linkification based on the file hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only - -- when a term has been defined in a glossary in a parent directory (`"parent"`) -- when it has been defined in a glossary next to the document file (`"sibling"`) -- or within the glossary itself (`"self"`). - -The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the [`glossaries`](#glossaries) option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. - -#### `linking.mentions` - -- **Range:** `"all" | "first-in-paragraph"` -- **Default:** `"all"` -- **Since:** v5.0.0 - -By default every mention of a term will be linkified. Sometimes this can -result in too much links affecting readability. This option provides finer -control of linkify behavior. - -#### `linking.paths` - -[opt-linking]: #linkingpaths - -- **Range:** `"relative" | "absolute" | "none" ` -- **Default:** `"relative"` - -Whether to create absolute or relative link-urls to the glossary. - -> **Important:** Using `"absolute"` without a `baseUrl` will produce an absolute file system path which you might not want to publish. - -#### `linking.pathComponents` - -- **Range:** `string[] with "path", "file", "ext"` -- **Default:** `["path", "file", "ext"]` -- **Since:** v6.0.0 - -Allows to tweak which components of a file path should make it into auto-generated links. Examples: - -- `["path", "file", "ext"]` => `./glossary/default.md#term` -- `["path", "file"]` => `./glossary/default#term` -- `["file"]` => `default#term` - -Use `linking.paths: "none"` if you would like to have a fragment (`#`) but no path components. - -#### `linking.pathRewrites` - -- **Range:** `{ [key: string]: string | string[] }` -- **Default:** `{}` -- **Since:** v6.2.0 - -Key-Value map where *Value* is a single search string or an array of strings or regular expressions (RegExp) and *Key* is the replacement/rewrite string. See also [Paths and Urls][doc-paths-and-urls]. - -#### `outDir` - -- **Range:** `string` - -The directory where to write output files to. - -> **Important:** using `.` or `./` is going to overwrite your input files. Only do this on a copy of your input -> files or if you are able to roll back any changes or if you know the outcome satisfies your needs. - -The recommendation is to write outputs to a separate directory such as `../out` or `../target` or `../docs-glossarified`. - -#### `outDirDropOld` - -- **Range:** `boolean` - -If `true` remove old `outDir` before writing a new one, otherwise overwrite files. Drops orphan files that have intentionally been removed from `baseDir`. - -#### `reportNotMentioned` - -- **Range:** `boolean` - -Report on terms which exist in a glossary but have neither been mentioned directly nor with any of its aliases. - -#### `unified` - -[opt-unified]: #unified - -- **Range:** `{ rcPath: string } | { settings: object, plugins: object|array }` - -Extended [unified configuration][unified-config]. See also [Markdown Syntax Extensions][doc-syntax-extensions]. - ## Special Thanks go to - [John Gruber](https://daringfireball.net/projects/markdown/), author of the Markdown syntax - [John MacFarlane et al.](https://github.com/commonmark-spec), initiators and authors of the CommonMark specification -- [Titus Wormer](https://github.com/wooorm), author of [unifiedjs](https://unifiedjs.com/), [remarkjs](https://github.com/remarkjs) and many more -- and all the other great people publishing modules of value to the tool - directly or transitively. +- [Titus Wormer](https://github.com/wooorm), author of [unifiedjs](https://unifiedjs.com/), [remarkjs](https://github.com/remarkjs) and so much more +- All the other great people publishing modules of value for the tool, be it directly or transitively. ## License diff --git a/conf/README.md b/conf/README.md index 23a40cf8..535a0e0d 100644 --- a/conf/README.md +++ b/conf/README.md @@ -1,22 +1,34 @@ -# Configuration +# Configure -[doc-readme]: ../README.md#install +[doc-readme]: ../doc/install.md +[doc-cli]: ../doc/cli.md -- [Config Format v5](./v5/doc/schema.md). -## Generate a config file with `--init` +[All config options (Config Format v5)](./v5/doc/schema.md) +~~~ +npx glossarify-md --config [file] +~~~ -Use `--init` to write a *minimal* config to the console. -- add `--more` to write a config with more options and default values -- add `--local` to load the config schema from the `node_modules` directory -- add `--new` to write a config to `./glossarify-md.conf.json` and a glossary to `./docs/glossary.md` +## Generate a config file -Examples: +~~~ +npx glossarify-md --init +~~~ -Write config to console +- add `--new` + - to write to a config file `./glossarify-md.conf.json` + - to create a glossary file `./docs/glossary.md` +- add `--local` to load the config `$schema` from `./node_modules` ([see below](#local-schema)) +- add `--more` to write a verbose config with more options and their default values + +*Example: Writing console outputs to a file* +~~~ +npx glossarify-md --init --local > my-own.conf.json ~~~ -npx glossarify-md --init --local + +*Example: Minimal configuration* +~~~ { "$schema": "./node_modules/glossarify-md/conf/v5/schema.json", "baseDir": "./docs", @@ -24,74 +36,39 @@ npx glossarify-md --init --local } ~~~ -Write config from console to a file -~~~ -npx glossarify-md --init --local > glossarify-md.conf.json -~~~ -Write config with default filename and initialize a ./doc/ directory with a glossary file. -~~~ -npx glossarify-md --init --local --new -~~~ > **ⓘ Paths** > > 1. `baseDir` and `$schema` are resolved relative to the config file or current working directory (when passed via CLI) > 1. all other paths are resolved relative to `baseDir` > 1. `outDir` *must not* be in `baseDir`so, if relative, must step out of `baseDir` - +> 1. prefer relative paths over absolute paths in the configuration ## Editor Support -Many IDEs and editors provide suggestions when editing JSON files that refer to a JSON Schema using a conventional `$schema` property. There are two ways to refer to a glossarify-md config schema. +Many IDEs and editors provide suggestions for JSON files with a `$schema` property locating a JSON Schema. -### Local Referencing with `--local` +### Local `$schema` -Local referencing is the **recommended** way **when glossarify-md was [installed "locally"][doc-readme] to a project**. It references the config schema of the glossarify-md version installed to the `./node_modules/` folder of the project. This way your editor can suggest all the latest options supported by the installed version. +... is **recommended** when glossarify-md was [installed][doc-readme] using `npm install` (*without* the `-g` switch). If supported, an editor loads the schema from the `./node_modules/` directory of your project, thus it can suggest you the config options matching your currently installed version of glossarify-md. -*glossarify-md.conf.json* -~~~ +~~~json { "$schema": "./node_modules/glossarify-md/conf/v5/schema.json" } ~~~ -### Web References +### Remote `$schema` -Web references are intended to be used when glossarify-md was installed "globally" using `npm install -g`. They will be generated when omitting the `--local` option. +...may be used when glossarify-md was installed using `npm install -g`. It requires editors downloading the schema from a remote location. -*glossarify-md.conf.json* -~~~ -{ - "$schema": "https://raw.githubusercontent.com/about-code/glossarify-md/v5.1.0/conf/v5/schema.json" -} -~~~ - -> **ⓘ** Note that the web reference contains a config *format version* `v5` but also a particular *release version* `v5.1.0`. The latter is the version by the glossarify-md release that generated the config. If you later install a newer version of glossarify-md (say `v5.2.0`) web references in your config files **will only get upgraded on breaking changes to the configuration format**. Thus your config files may keep on referring to `v5.1.0`. Due to backwards compatibility this isn't a problem but your editor won't suggest you *the latest* options that could be used with glossarify-md `v5.2.0`. For this to happen change the *release version* in the path, manually. - - - - +> **ⓘ Note** The remote `$schema` URL contains a config *format version* (`v5`) and a glossarify-md *release version* (`v6.1.0`). The release version is the glossarify-md version *which initially generated the config file*. When you install a newer release of glossarify-md (say `v6.2.0`) the URL *won't* be updated and keeps on referring to `v6.1.0`. Therefore, your editor or IDE won't suggest you *the latest* options available for `v6.2.0` when editing the config file. However, glossarify-md will inform you when it detects this situation. +> +> On breaking changes affecting the *format version* glossarify-md will attempt to provide assistance on upgrading your configuration files including the `$schema` URL. This should happen *rarely*, though. \ No newline at end of file diff --git a/conf/v5/doc/schema-defs-csvdialect-properties-delimiter.md b/conf/v5/doc/schema-defs-csvdialect-properties-delimiter.md new file mode 100644 index 00000000..a6e24550 --- /dev/null +++ b/conf/v5/doc/schema-defs-csvdialect-properties-delimiter.md @@ -0,0 +1,7 @@ +## delimiter Default Value + +The default value is: + +```json +";" +``` diff --git a/conf/v5/doc/schema-defs-csvdialect-properties-escapechar.md b/conf/v5/doc/schema-defs-csvdialect-properties-escapechar.md new file mode 100644 index 00000000..bac5afa4 --- /dev/null +++ b/conf/v5/doc/schema-defs-csvdialect-properties-escapechar.md @@ -0,0 +1,7 @@ +## escapeChar Default Value + +The default value is: + +```json +"\"" +``` diff --git a/conf/v5/doc/schema-defs-csvdialect-properties-quotechar.md b/conf/v5/doc/schema-defs-csvdialect-properties-quotechar.md new file mode 100644 index 00000000..99200db2 --- /dev/null +++ b/conf/v5/doc/schema-defs-csvdialect-properties-quotechar.md @@ -0,0 +1,7 @@ +## quoteChar Default Value + +The default value is: + +```json +"\"" +``` diff --git a/conf/v5/doc/schema-defs-csvdialect.md b/conf/v5/doc/schema-defs-csvdialect.md new file mode 100644 index 00000000..98a376d4 --- /dev/null +++ b/conf/v5/doc/schema-defs-csvdialect.md @@ -0,0 +1,67 @@ +## dialect Default Value + +The default value is: + +```json +{ + "delimiter": ";" +} +``` + +# dialect Properties + + + +## delimiter + +A character sequence to use as the field separator. + +`delimiter` + +* is required + +* Type: `string` + +### delimiter Default Value + +The default value is: + +```json +";" +``` + +## quoteChar + +A one-character string for surrounding field values in CSV data (no matter whether being a numeric value or an alphanumeric value or something else). Uses the quote character " by default. A CSV field whose field value is text containing quotes is required to embed the whole text value between two `quoteChar` as well as escaping the quotes in the text data using `escapeChar`. For example a raw value of ;This is "quoted" text; is expected to be encoded in CSV as ;"This is ""quoted"" text"; where the outer quotes are `quoteChars` and the inner quotes each are preceeded by an `escapeChar` (which is a quote character by default, either). + +`quoteChar` + +* is optional + +* Type: `string` + +### quoteChar Default Value + +The default value is: + +```json +"\"" +``` + +## escapeChar + +Specifies a one-character string to use as an escape character within a field value. Uses the quote " character as a default which requires encoding quotes in text data using two consecutive quotes (one being the escape character and one being the actual quote of the data). This is a very common encoding scheme. However, change this to an empty string to disable escaping, completely or use another character as needed. + +`escapeChar` + +* is optional + +* Type: `string` + +### escapeChar Default Value + +The default value is: + +```json +"\"" +``` diff --git a/conf/v5/doc/schema-defs-csvtableschema-properties-fields-items.md b/conf/v5/doc/schema-defs-csvtableschema-properties-fields-items.md new file mode 100644 index 00000000..558689b1 --- /dev/null +++ b/conf/v5/doc/schema-defs-csvtableschema-properties-fields-items.md @@ -0,0 +1,21 @@ +# items Properties + + + +## name + +A name for this field. + +`name` + +* is optional + +* Type: `string` + +### name Default Value + +The default value is: + +```json +"http://www.w3.org/2004/02/skos/core#" +``` diff --git a/conf/v5/doc/schema-defs-csvtableschema-properties-fields.md b/conf/v5/doc/schema-defs-csvtableschema-properties-fields.md new file mode 100644 index 00000000..d69a5e19 --- /dev/null +++ b/conf/v5/doc/schema-defs-csvtableschema-properties-fields.md @@ -0,0 +1,3 @@ +## fields Constraints + +**minimum number of items**: the minimum number of items for this array is: `1` diff --git a/conf/v5/doc/schema-defs-csvtableschema.md b/conf/v5/doc/schema-defs-csvtableschema.md new file mode 100644 index 00000000..c09a853e --- /dev/null +++ b/conf/v5/doc/schema-defs-csvtableschema.md @@ -0,0 +1,17 @@ +# schema Properties + + + +## fields + + + +`fields` + +* is required + +* Type: `object[]` ([Details](schema-defs-csvtableschemafield.md)) + +### fields Constraints + +**minimum number of items**: the minimum number of items for this array is: `1` diff --git a/conf/v5/doc/schema-defs-csvtableschemafield-properties-name.md b/conf/v5/doc/schema-defs-csvtableschemafield-properties-name.md new file mode 100644 index 00000000..b886faca --- /dev/null +++ b/conf/v5/doc/schema-defs-csvtableschemafield-properties-name.md @@ -0,0 +1,7 @@ +## name Default Value + +The default value is: + +```json +"http://www.w3.org/2004/02/skos/core#" +``` diff --git a/conf/v5/doc/schema-defs-csvtableschemafield.md b/conf/v5/doc/schema-defs-csvtableschemafield.md new file mode 100644 index 00000000..558689b1 --- /dev/null +++ b/conf/v5/doc/schema-defs-csvtableschemafield.md @@ -0,0 +1,21 @@ +# items Properties + + + +## name + +A name for this field. + +`name` + +* is optional + +* Type: `string` + +### name Default Value + +The default value is: + +```json +"http://www.w3.org/2004/02/skos/core#" +``` diff --git a/conf/v5/doc/schema-defs-csvtableschemafieldname.md b/conf/v5/doc/schema-defs-csvtableschemafieldname.md new file mode 100644 index 00000000..b886faca --- /dev/null +++ b/conf/v5/doc/schema-defs-csvtableschemafieldname.md @@ -0,0 +1,7 @@ +## name Default Value + +The default value is: + +```json +"http://www.w3.org/2004/02/skos/core#" +``` diff --git a/conf/v5/doc/schema-defs-glossaryfile-properties-import.md b/conf/v5/doc/schema-defs-glossaryfile-properties-import.md index 423f467c..cf1a3e15 100644 --- a/conf/v5/doc/schema-defs-glossaryfile-properties-import.md +++ b/conf/v5/doc/schema-defs-glossaryfile-properties-import.md @@ -4,7 +4,7 @@ ## file -The JSON file to import terms from. +The file to import terms from. Supported file content types: 'application/json', 'application/ld+json', 'application/n-quads'. `file` @@ -14,7 +14,7 @@ The JSON file to import terms from. ## context -File path or URL to a custom JSON-LD context document. Expected to map attributes and type names of a custom import document format onto terms of the well-known W3C SKOS vocabulary. +File path or URL to a custom JSON-LD context document (application/ld+json) mapping format terminology (attributes, type names) of a JSON data document ('application/json') onto well-known W3C SKOS terminology. `context` diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-if-properties-file.md b/conf/v5/doc/schema-defs-glossaryfileimport-if-properties-file.md new file mode 100644 index 00000000..8877e1a4 --- /dev/null +++ b/conf/v5/doc/schema-defs-glossaryfileimport-if-properties-file.md @@ -0,0 +1,9 @@ +## file Constraints + +**pattern**: the string must match the following regular expression: + +```regexp +^(.*).csv$ +``` + +[try pattern](https://regexr.com/?expression=%5E\(.\*\).csv%24 "try regular expression with regexr.com") diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-if-properties.md b/conf/v5/doc/schema-defs-glossaryfileimport-if-properties.md new file mode 100644 index 00000000..e69de29b diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-if.md b/conf/v5/doc/schema-defs-glossaryfileimport-if.md new file mode 100644 index 00000000..91053ad9 --- /dev/null +++ b/conf/v5/doc/schema-defs-glossaryfileimport-if.md @@ -0,0 +1,23 @@ +# if Properties + + + +## file + + + +`file` + +* is optional + +* Type: `string` + +### file Constraints + +**pattern**: the string must match the following regular expression: + +```regexp +^(.*).csv$ +``` + +[try pattern](https://regexr.com/?expression=%5E\(.\*\).csv%24 "try regular expression with regexr.com") diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-dialect-default.md b/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-dialect-default.md new file mode 100644 index 00000000..e69de29b diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-dialect.md b/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-dialect.md new file mode 100644 index 00000000..98a376d4 --- /dev/null +++ b/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-dialect.md @@ -0,0 +1,67 @@ +## dialect Default Value + +The default value is: + +```json +{ + "delimiter": ";" +} +``` + +# dialect Properties + + + +## delimiter + +A character sequence to use as the field separator. + +`delimiter` + +* is required + +* Type: `string` + +### delimiter Default Value + +The default value is: + +```json +";" +``` + +## quoteChar + +A one-character string for surrounding field values in CSV data (no matter whether being a numeric value or an alphanumeric value or something else). Uses the quote character " by default. A CSV field whose field value is text containing quotes is required to embed the whole text value between two `quoteChar` as well as escaping the quotes in the text data using `escapeChar`. For example a raw value of ;This is "quoted" text; is expected to be encoded in CSV as ;"This is ""quoted"" text"; where the outer quotes are `quoteChars` and the inner quotes each are preceeded by an `escapeChar` (which is a quote character by default, either). + +`quoteChar` + +* is optional + +* Type: `string` + +### quoteChar Default Value + +The default value is: + +```json +"\"" +``` + +## escapeChar + +Specifies a one-character string to use as an escape character within a field value. Uses the quote " character as a default which requires encoding quotes in text data using two consecutive quotes (one being the escape character and one being the actual quote of the data). This is a very common encoding scheme. However, change this to an empty string to disable escaping, completely or use another character as needed. + +`escapeChar` + +* is optional + +* Type: `string` + +### escapeChar Default Value + +The default value is: + +```json +"\"" +``` diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-title.md b/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-title.md new file mode 100644 index 00000000..0598b0fa --- /dev/null +++ b/conf/v5/doc/schema-defs-glossaryfileimport-then-properties-title.md @@ -0,0 +1,7 @@ +## title Default Value + +The default value is: + +```json +"Glossary" +``` diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-then-properties.md b/conf/v5/doc/schema-defs-glossaryfileimport-then-properties.md new file mode 100644 index 00000000..e69de29b diff --git a/conf/v5/doc/schema-defs-glossaryfileimport-then.md b/conf/v5/doc/schema-defs-glossaryfileimport-then.md new file mode 100644 index 00000000..55671a76 --- /dev/null +++ b/conf/v5/doc/schema-defs-glossaryfileimport-then.md @@ -0,0 +1,55 @@ +# then Properties + + + +## title + + + +`title` + +* is optional + +* Type: `string` + +### title Default Value + +The default value is: + +```json +"Glossary" +``` + +## dialect + +A CSV dialect descriptor. Similar to dialect in a tabular data resource schema. + +`dialect` + +* is optional + +* Type: `object` ([Details](schema-defs-csvdialect.md)) + +### dialect Default Value + +The default value is: + +```json +{ + "delimiter": ";" +} +``` + +## schema + +A mapping of CSV table fields onto SKOS terms, e.g. +"fields": \[ +{ "rdfType": " "}, +{ "rdfType": "http\://www\.w3.org/2004/02/skos/core#prefLabel "} +]. Aims to be compatible with Tabular Data Resource schema. + +`schema` + +* is optional + +* Type: `object` ([Details](schema-defs-csvtableschema.md)) diff --git a/conf/v5/doc/schema-defs-glossaryfileimport.md b/conf/v5/doc/schema-defs-glossaryfileimport.md index 0a294919..8a437bc8 100644 --- a/conf/v5/doc/schema-defs-glossaryfileimport.md +++ b/conf/v5/doc/schema-defs-glossaryfileimport.md @@ -4,7 +4,7 @@ ## file -The JSON file to import terms from. +The file to import terms from. Supported file content types: 'application/json', 'application/ld+json', 'application/n-quads'. `file` @@ -14,7 +14,7 @@ The JSON file to import terms from. ## context -File path or URL to a custom JSON-LD context document. Expected to map attributes and type names of a custom import document format onto terms of the well-known W3C SKOS vocabulary. +File path or URL to a custom JSON-LD context document (application/ld+json) mapping format terminology (attributes, type names) of a JSON data document ('application/json') onto well-known W3C SKOS terminology. `context` diff --git a/conf/v5/doc/schema-defs-indexing.md b/conf/v5/doc/schema-defs-indexing.md index 523a9dc2..d894b17f 100644 --- a/conf/v5/doc/schema-defs-indexing.md +++ b/conf/v5/doc/schema-defs-indexing.md @@ -20,7 +20,7 @@ Level of detail by which to group occurrences of terms or syntactic elements in ## headingDepths -An array with items in a range of 1-6 denoting the depths of headings that should be indexed for cross-linking. Excluding headings from indexing is mostly a performance optimization, applicable when only headings at a particular depth should participate in id-based cross-linking or term-based auto linking. Note that it is possible to keep indexing all headings to support manually written id-based cross-links for all headings but restricting auto-linking to a subset of headings at a particular depth using `linking.headingDepths` (see `linking` options). +An array with items in a range of 1-6 denoting the depths of headings that should be indexed for cross-linking. Most of the time `linking.headingDepths` should be preferred to exclude certain headings from term-based auto linking. Excluding headings from indexing not only affects auto-linking but more such as path resolution for manual ID-based cross-links, generation of lists or book indexes and other features. Excluding headings from indexing is mostly a performance optimization applicable when headings at a particular level are never used or never required to be linkified. `headingDepths` diff --git a/conf/v5/doc/schema-defs-linking.md b/conf/v5/doc/schema-defs-linking.md index 874a3110..dfe90177 100644 --- a/conf/v5/doc/schema-defs-linking.md +++ b/conf/v5/doc/schema-defs-linking.md @@ -133,11 +133,11 @@ When true appends pandoc-style {#...} heading identifiers where necessary. Note ## limitByAlternatives -This option can be used to limit the number of links, if there are multiple definitions of a term. When using a positive value, then the system creates links *no more than ...* alternative links. If the number is negative then the absolute amount indicates to *not link a term at all once there are at least ...* alternative definitions. For example: -1 linkifies the term in text and adds a link to 1 alternative definition (superscript), -0 only linkifies the term in text but adds 0 links to alternative definitions, -\-1 does not linkify a term in text once there is at least 1 alternative definition. -Negative values may also be helpful when using 'glossaries' option with a glob pattern and there are multiple documents that follow a certain template and thus repeatedly declare the same heading (= term). +This option can be used to deal with ambiguities and limit the number of links in case of multiple definitions of a term. For example, a value of +5: makes the system link to *at most 5* alternative definitions per term +\-5: makes the system *stop linking a term* once there are *at least 5* alternative definitions +0: links the term to a single definition but provides 0 indication of alternative definitions (even if there are any). +Negative values may also be helpful when using 'glossaries' option with a glob pattern and there are multiple documents that follow a certain heading template such that the same heading appears more than once. `limitByAlternatives` @@ -147,7 +147,7 @@ Negative values may also be helpful when using 'glossaries' option with a glob p ## limitByTermOrigin -Limits linkification based on the file hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only when a term has been defined in a glossary in a parent directory ("parent") or when it has been defined in a glossary next to the document file ("sibling") or within the glossary itself ("self"). The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the `glossaries` option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. +Limits linkification based on the filesystem hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only when a term has been defined in a glossary in a parent directory ("parent") or when it has been defined in a glossary next to the document file ("sibling") or within the glossary itself ("self"). The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the `glossaries` option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. `limitByTermOrigin` diff --git a/conf/v5/doc/schema-properties-indexing.md b/conf/v5/doc/schema-properties-indexing.md index dca62dbe..cfcc3738 100644 --- a/conf/v5/doc/schema-properties-indexing.md +++ b/conf/v5/doc/schema-properties-indexing.md @@ -38,7 +38,7 @@ Level of detail by which to group occurrences of terms or syntactic elements in ## headingDepths -An array with items in a range of 1-6 denoting the depths of headings that should be indexed for cross-linking. Excluding headings from indexing is mostly a performance optimization, applicable when only headings at a particular depth should participate in id-based cross-linking or term-based auto linking. Note that it is possible to keep indexing all headings to support manually written id-based cross-links for all headings but restricting auto-linking to a subset of headings at a particular depth using `linking.headingDepths` (see `linking` options). +An array with items in a range of 1-6 denoting the depths of headings that should be indexed for cross-linking. Most of the time `linking.headingDepths` should be preferred to exclude certain headings from term-based auto linking. Excluding headings from indexing not only affects auto-linking but more such as path resolution for manual ID-based cross-links, generation of lists or book indexes and other features. Excluding headings from indexing is mostly a performance optimization applicable when headings at a particular level are never used or never required to be linkified. `headingDepths` diff --git a/conf/v5/doc/schema-properties-linking.md b/conf/v5/doc/schema-properties-linking.md index f6855fb4..02484b49 100644 --- a/conf/v5/doc/schema-properties-linking.md +++ b/conf/v5/doc/schema-properties-linking.md @@ -164,11 +164,11 @@ When true appends pandoc-style {#...} heading identifiers where necessary. Note ## limitByAlternatives -This option can be used to limit the number of links, if there are multiple definitions of a term. When using a positive value, then the system creates links *no more than ...* alternative links. If the number is negative then the absolute amount indicates to *not link a term at all once there are at least ...* alternative definitions. For example: -1 linkifies the term in text and adds a link to 1 alternative definition (superscript), -0 only linkifies the term in text but adds 0 links to alternative definitions, -\-1 does not linkify a term in text once there is at least 1 alternative definition. -Negative values may also be helpful when using 'glossaries' option with a glob pattern and there are multiple documents that follow a certain template and thus repeatedly declare the same heading (= term). +This option can be used to deal with ambiguities and limit the number of links in case of multiple definitions of a term. For example, a value of +5: makes the system link to *at most 5* alternative definitions per term +\-5: makes the system *stop linking a term* once there are *at least 5* alternative definitions +0: links the term to a single definition but provides 0 indication of alternative definitions (even if there are any). +Negative values may also be helpful when using 'glossaries' option with a glob pattern and there are multiple documents that follow a certain heading template such that the same heading appears more than once. `limitByAlternatives` @@ -178,7 +178,7 @@ Negative values may also be helpful when using 'glossaries' option with a glob p ## limitByTermOrigin -Limits linkification based on the file hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only when a term has been defined in a glossary in a parent directory ("parent") or when it has been defined in a glossary next to the document file ("sibling") or within the glossary itself ("self"). The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the `glossaries` option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. +Limits linkification based on the filesystem hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only when a term has been defined in a glossary in a parent directory ("parent") or when it has been defined in a glossary next to the document file ("sibling") or within the glossary itself ("self"). The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the `glossaries` option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. `limitByTermOrigin` diff --git a/conf/v5/doc/schema.md b/conf/v5/doc/schema.md index cf2e7844..c5ed106f 100644 --- a/conf/v5/doc/schema.md +++ b/conf/v5/doc/schema.md @@ -126,7 +126,7 @@ The default value is: ## indexing -Path or glob patterns of files to include for linking to glossaries. +Options configuring the indexer. `indexing` @@ -318,12 +318,138 @@ The default value is: # Configuration Schema Definitions +## Definitions group csvDialect + +Reference this group by using + +```json +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/csvDialect"} +``` + + + +### delimiter + +A character sequence to use as the field separator. + +`delimiter` + +* is required + +* Type: `string` + +#### delimiter Default Value + +The default value is: + +```json +";" +``` + +### quoteChar + +A one-character string for surrounding field values in CSV data (no matter whether being a numeric value or an alphanumeric value or something else). Uses the quote character " by default. A CSV field whose field value is text containing quotes is required to embed the whole text value between two `quoteChar` as well as escaping the quotes in the text data using `escapeChar`. For example a raw value of ;This is "quoted" text; is expected to be encoded in CSV as ;"This is ""quoted"" text"; where the outer quotes are `quoteChars` and the inner quotes each are preceeded by an `escapeChar` (which is a quote character by default, either). + +`quoteChar` + +* is optional + +* Type: `string` + +#### quoteChar Default Value + +The default value is: + +```json +"\"" +``` + +### escapeChar + +Specifies a one-character string to use as an escape character within a field value. Uses the quote " character as a default which requires encoding quotes in text data using two consecutive quotes (one being the escape character and one being the actual quote of the data). This is a very common encoding scheme. However, change this to an empty string to disable escaping, completely or use another character as needed. + +`escapeChar` + +* is optional + +* Type: `string` + +#### escapeChar Default Value + +The default value is: + +```json +"\"" +``` + +## Definitions group csvTableSchema + +Reference this group by using + +```json +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/csvTableSchema"} +``` + + + +### fields + + + +`fields` + +* is required + +* Type: `object[]` ([Details](schema-defs-csvtableschema-properties-fields-items.md)) + +#### fields Constraints + +**minimum number of items**: the minimum number of items for this array is: `1` + +## Definitions group csvTableSchemaField + +Reference this group by using + +```json +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/csvTableSchemaField"} +``` + + + +### name + +A name for this field. + +`name` + +* is optional + +* Type: `string` + +#### name Default Value + +The default value is: + +```json +"http://www.w3.org/2004/02/skos/core#" +``` + +## Definitions group csvTableSchemaFieldName + +Reference this group by using + +```json +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/csvTableSchemaFieldName"} +``` + + + ## Definitions group generateFiles Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/generateFiles"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/generateFiles"} ``` @@ -383,7 +509,7 @@ Generate a file with a list of tables and where they can be found. Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/glossaryFile"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/glossaryFile"} ``` @@ -486,7 +612,7 @@ A namespace or vocabulary identifier used as a prefix to construct URIs for glos Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/glossaryFileExport"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/glossaryFileExport"} ``` @@ -516,14 +642,14 @@ File path or URL to a custom JSON-LD context document. JSON-LD contexts map term Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/glossaryFileImport"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/glossaryFileImport"} ``` ### file -The JSON file to import terms from. +The file to import terms from. Supported file content types: 'application/json', 'application/ld+json', 'application/n-quads'. `file` @@ -533,7 +659,7 @@ The JSON file to import terms from. ### context -File path or URL to a custom JSON-LD context document. Expected to map attributes and type names of a custom import document format onto terms of the well-known W3C SKOS vocabulary. +File path or URL to a custom JSON-LD context document (application/ld+json) mapping format terminology (attributes, type names) of a JSON data document ('application/json') onto well-known W3C SKOS terminology. `context` @@ -546,7 +672,7 @@ File path or URL to a custom JSON-LD context document. Expected to map attribute Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/indexFile"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/indexFile"} ``` @@ -596,7 +722,7 @@ When this is `false` (default) then term occurrences in sections deeper than `in Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/indexing"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/indexing"} ``` @@ -619,7 +745,7 @@ Level of detail by which to group occurrences of terms or syntactic elements in ### headingDepths -An array with items in a range of 1-6 denoting the depths of headings that should be indexed for cross-linking. Excluding headings from indexing is mostly a performance optimization, applicable when only headings at a particular depth should participate in id-based cross-linking or term-based auto linking. Note that it is possible to keep indexing all headings to support manually written id-based cross-links for all headings but restricting auto-linking to a subset of headings at a particular depth using `linking.headingDepths` (see `linking` options). +An array with items in a range of 1-6 denoting the depths of headings that should be indexed for cross-linking. Most of the time `linking.headingDepths` should be preferred to exclude certain headings from term-based auto linking. Excluding headings from indexing not only affects auto-linking but more such as path resolution for manual ID-based cross-links, generation of lists or book indexes and other features. Excluding headings from indexing is mostly a performance optimization applicable when headings at a particular level are never used or never required to be linkified. `headingDepths` @@ -632,7 +758,7 @@ An array with items in a range of 1-6 denoting the depths of headings that shoul Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/listOfItemsFile"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/listOfItemsFile"} ``` @@ -682,7 +808,7 @@ A regular expression which when matching against text will generate an entry in Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/i18n"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/i18n"} ``` @@ -801,7 +927,7 @@ Whether the comparison is for sorting or for searching for matching strings. Def Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/linking"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/linking"} ``` @@ -937,11 +1063,11 @@ When true appends pandoc-style {#...} heading identifiers where necessary. Note ### limitByAlternatives -This option can be used to limit the number of links, if there are multiple definitions of a term. When using a positive value, then the system creates links *no more than ...* alternative links. If the number is negative then the absolute amount indicates to *not link a term at all once there are at least ...* alternative definitions. For example: -1 linkifies the term in text and adds a link to 1 alternative definition (superscript), -0 only linkifies the term in text but adds 0 links to alternative definitions, -\-1 does not linkify a term in text once there is at least 1 alternative definition. -Negative values may also be helpful when using 'glossaries' option with a glob pattern and there are multiple documents that follow a certain template and thus repeatedly declare the same heading (= term). +This option can be used to deal with ambiguities and limit the number of links in case of multiple definitions of a term. For example, a value of +5: makes the system link to *at most 5* alternative definitions per term +\-5: makes the system *stop linking a term* once there are *at least 5* alternative definitions +0: links the term to a single definition but provides 0 indication of alternative definitions (even if there are any). +Negative values may also be helpful when using 'glossaries' option with a glob pattern and there are multiple documents that follow a certain heading template such that the same heading appears more than once. `limitByAlternatives` @@ -951,7 +1077,7 @@ Negative values may also be helpful when using 'glossaries' option with a glob p ### limitByTermOrigin -Limits linkification based on the file hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only when a term has been defined in a glossary in a parent directory ("parent") or when it has been defined in a glossary next to the document file ("sibling") or within the glossary itself ("self"). The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the `glossaries` option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. +Limits linkification based on the filesystem hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only when a term has been defined in a glossary in a parent directory ("parent") or when it has been defined in a glossary next to the document file ("sibling") or within the glossary itself ("self"). The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the `glossaries` option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. `limitByTermOrigin` @@ -974,7 +1100,7 @@ When 'true' replaces markdown inline links with numbered references to a link re Reference this group by using ```json -{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.1/conf/v5/schema.json#/$defs/unified"} +{"$ref":"https://raw.githubusercontent.com/about-code/glossarify-md/v6.3.3/conf/v5/schema.json#/$defs/unified"} ``` @@ -1016,7 +1142,7 @@ Unified *processor* settings as described in + +#### [glossarify-md](#glossarify-md) + + + +#### [README.md](#readmemd) + + + +#### [Table of Contents](#table-of-contents) + + diff --git a/doc/_references.md b/doc/_references.md index 50ce7742..21490c46 100644 --- a/doc/_references.md +++ b/doc/_references.md @@ -4,7 +4,7 @@ -[Atom][1] Code Editor. +[Atom 🌎][1] Code Editor. ## [CommonMark](#commonmark) @@ -19,7 +19,7 @@ Effort on providing a minimal set of standardized Markdown syntax. aliases: 'DC, DublinCore, dc:' --> -The [Dublin Core][2] Metadata Initiative. +The [Dublin Core 🌎][2] Metadata Initiative. ## [GFM](#gfm) @@ -28,25 +28,25 @@ The [Dublin Core][2] Metadata Initiative. aliases: GFM, GitHub Flavoured Markdown, GitHub Flavored Markdown --> -[GitHub Flavoured Markdown][3] +[GitHub Flavoured Markdown 🌎][3] + +## [GitHub Pages](#github-pages) + + + +[GitHub Pages 🌎][4] is a static website rendering and publishing service by GitHub Inc. ## [github-slugger](#github-slugger) -A library providing support for [slugs★][4]. See [github-slugger][5]. +A library providing support for [slugs][5]. See [github-slugger 🌎][6]. ## [glob](#glob) -A file pattern matcher. See [glob][6]. - -## [glossarify-md](#glossarify-md) - - - -This project. +A file pattern matcher. See [glob 🌎][7]. ## [Hugo](#hugo) @@ -67,7 +67,7 @@ A static website renderer compiling an HTML website from Markdown files. aliases: JSON-LD Spec --> -[JSON-LD][7] is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public [vocabularies★][8]. With JSON-LD it's possible to write applications which are interoperable by mutual agreement on the same public vocabulary. [SKOS][9] is one such vocabulary supported by [glossarify-md][10] +[JSON-LD 🌎][8] is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public [vocabularies][9]. With JSON-LD it's possible to write applications which are interoperable by mutual agreement on the same public vocabulary. [SKOS 🌎][10] is one such vocabulary supported by [glossarify-md][11] ## [jsonld Library](#jsonld-library) @@ -76,7 +76,7 @@ A static website renderer compiling an HTML website from Markdown files. aliases: jsonld --> -A JavaScript implementation of [JSON-LD][7]. +A JavaScript implementation of [JSON-LD 🌎][8]. ## [Linked Data](#linked-data) @@ -85,7 +85,7 @@ A JavaScript implementation of [JSON-LD][7]. aliases: LD --> -See [Linked Data][11]. +See [Linked Data 🌎][12]. ## [mdAst](#mdast) @@ -96,15 +96,19 @@ See [Linked Data][11]. Specification and Implementation of a Markdown Abstract Syntax Tree. +## [mdast-util-visit](#mdast-util-visit) + + + ## [micromark](#micromark) -A low-level extensible implementation of the [CommonMark][12] syntax specification (parsing and tokenizing). +A low-level extensible implementation of the [CommonMark 🌎][13] syntax specification (parsing and tokenizing). ## [NodeJS](#nodejs) - @@ -113,7 +117,7 @@ A low-level extensible implementation of the [CommonMark][12] syntax specificati -Node Package Manager. See [npm][13]. +Node Package Manager. See [npm 🌎][14]. ## [OWL](#owl) @@ -125,49 +129,71 @@ Web Ontology Language. -See [pandoc][14]. +See [pandoc 🌎][15]. ## [PlantUML](#plantuml) -Generates diagrams from text files written in the [PlantUML][15] syntax. +Generates diagrams from text files written in the [PlantUML 🌎][16] syntax. ## [remark](#remark) -*[remark][16]* is a parser and compiler project under the [unified][17] umbrella for *Markdown* text files in particular. +*[remark 🌎][17]* is a parser and compiler project under the [unified 🌎][18] umbrella for *Markdown* text files in particular. ## [remark-frontmatter](#remark-frontmatter) -A [remark][16] syntax plug-in supporting pseudo-standard front-matter syntax. +A [remark 🌎][17] syntax plug-in supporting pseudo-standard front-matter syntax. + +## [remark-gfm](#remark-gfm) + + + +A [remark 🌎][17] syntax plug-in supporting [GitHub Flavoured Markdown 🌎][3]. + +## [remark plug-ins](#remark-plug-ins) + + + +A curated list of [remark 🌎][17] [plug-ins][19]. ## [remark-shortcodes](#remark-shortcodes) -A [remark][16] syntax plug-in supporting non-standard [Hugo][18] shortcodes syntax. +A [remark 🌎][17] syntax plug-in supporting non-standard [Hugo 🌎][20] shortcodes syntax. + +## [Semantic HTML Tags](#semantic-html-tags) + + ## [SKOS](#skos) -With the Simple [Knowledge Organization System★][19] ([SKOS][9]) the World Wide Web Consortium (W3C) has standardized a (meta-)[vocabulary★][8] which is suited and intended for modeling *Simple Knowledge Organization Systems* such as Glossaries, Thesauri, Taxonomies or Word Nets. +With the Simple [Knowledge Organization System][21] ([SKOS 🌎][10]) the World Wide Web Consortium (W3C) has standardized a (meta-)[vocabulary][9] which is suited and intended for modeling *Simple Knowledge Organization Systems* such as Glossaries, Thesauri, Taxonomies or Word Nets. ## [unified](#unified) -*[unified][17]* is an umbrella project around *text file processing in general*. See also [Conceptual Layers of glossarify-md][20] +*[unified 🌎][18]* is an umbrella project around *text file processing in general*. See also [Conceptual Layers][22] of [glossarify-md][11]. ## [URN](#urn) -Uniform Resource Names. See [URN][21]. +Uniform Resource Names. See [URN 🌎][23]. ## [VSCode](#vscode) @@ -175,7 +201,7 @@ Uniform Resource Names. See [URN][21]. [Code-OSS]: https://github.com/microsoft/vscode -Visual Studio Code. See [VSCode][22] or [Code-OSS]. +Visual Studio Code. See [VSCode 🌎][24] or [Code-OSS]. ## [vuepress](#vuepress) @@ -189,46 +215,58 @@ A static website generator translating markdown files into a website powered by A Single Page Application framework written in JavaScript. +## [verdaccio](#verdaccio) + + + +An easy to [install][25] local or on-premises [npm 🌎][14] registry. + [1]: https://atom.io "Atom Code Editor." [2]: http://purl.org/dc/terms/ "The Dublin Core Metadata Initiative." [3]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" -[4]: ./glossary.md#slug "A slug is a URL-friendly identifier that can be used within URL fragments to address headings / sections on a page." +[4]: https://pages.github.com/ "GitHub Pages is a static website rendering and publishing service by GitHub Inc." + +[5]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#slug "A slug is a URL-friendly identifier that can be used within URL fragments to address headings / sections on a page." + +[6]: https://npmjs.com/package/github-slugger "A library providing support for slugs." + +[7]: https://github.com/isaacs/node-glob#glob-primer "A file pattern matcher." -[5]: https://npmjs.com/package/github-slugger "A library providing support for slugs." +[8]: https://json-ld.org "JSON-LD is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public vocabularies." -[6]: https://github.com/isaacs/node-glob#glob-primer "A file pattern matcher." +[9]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#vocabulary "A collection of terms which is uniquely identifiable." -[7]: https://json-ld.org "JSON-LD is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public vocabularies." +[10]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets." -[8]: ./glossary.md#vocabulary "A collection of terms which is uniquely identifiable." +[11]: https://github.com/about-code/glossarify-md -[9]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets." +[12]: https://www.w3.org/standards/semanticweb/ontology "See Linked Data." -[10]: https://github.com/about-code/glossarify-md "This project." +[13]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." -[11]: https://www.w3.org/standards/semanticweb/ontology "See Linked Data." +[14]: https://npmjs.com "Node Package Manager." -[12]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." +[15]: https://pandoc.org "See pandoc." -[13]: https://npmjs.com "Node Package Manager." +[16]: https://plantuml.com "Generates diagrams from text files written in the PlantUML syntax." -[14]: https://pandoc.org "See pandoc." +[17]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." -[15]: https://plantuml.com "Generates diagrams from text files written in the PlantUML syntax." +[18]: https://unifiedjs.com "unified is an umbrella project around text file processing in general." -[16]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." +[19]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins.md#installing-and-configuring-plug-ins "The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp." -[17]: https://unifiedjs.com "unified is an umbrella project around text file processing in general." +[20]: https://gohugo.io "A static website renderer compiling an HTML website from Markdown files." -[18]: https://gohugo.io "A static website renderer compiling an HTML website from Markdown files." +[21]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#kos---knowledge-organization-systems "Glossaries are considered a kind of Knowledge Organisation System (KOS) which organizes knowledge as a list of terms and term definitions." -[19]: ./glossary.md#kos---knowledge-organization-systems "Glossaries are considered a kind of Knowledge Organisation System (KOS) which organizes knowledge as a list of terms and term definitions." +[22]: https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md#internals-conceptual-layers "Conceptual layers of text processing by glossarify-md and projects contributing to each layer glossarify-md is built on unified, an umbrella project for text file processing in general." -[20]: ./conceptual-layers.md +[23]: https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml "Uniform Resource Names." -[21]: https://www.iana.org/assignments/urn-namespaces/urn-namespaces.xhtml "Uniform Resource Names." +[24]: https://code.visualstudio.com "Visual Studio Code." -[22]: https://code.visualstudio.com "Visual Studio Code." +[25]: https://github.com/about-code/glossarify-md/blob/master/doc/install.md#install diff --git a/doc/cli.md b/doc/cli.md index 8020b1d0..f111c91f 100644 --- a/doc/cli.md +++ b/doc/cli.md @@ -1,25 +1,33 @@ # [Command Line Interface](#command-line-interface) -Get a list of command line arguments by passing `--help`. - -## [Shortcuts](#shortcuts) - -If you have installed [glossarify-md][1] locally to a project folder with a `package.json` then you can define an `npm run` script in the `scripts` section of your `package.json`: - -*package.json* - -```json -{ - "scripts": { - "glossarify": "glossarify-md --config ./glossarify-md.conf.json" - } -} -``` - -Next time you can run [glossarify-md][1] by just typing line 1. Pass arguments after a `--` separator (line 2). - - 1 | npm run glossarify - 2 | npm run glossarify -- --help + + +## [`--help`](#--help) + +Get a complete list of available command line arguments. + +## [`--config [file]`](#--config-file) + + npx glossarify-md --config ./glossarify-md.conf.json + +> **Tipp:** If you have installed glossarify-md locally to a project folder with a `package.json` then you can define an `npm run` script in the `scripts` section of your `package.json`: +> +> *package.json* +> +> ```json +> { +> "scripts": { +> "glossarify": "glossarify-md --config ./glossarify-md.conf.json" +> } +> } +> ``` +> +> Next time you can run glossarify-md by just typing line 1. Pass arguments after a `--` separator (line 2). +> +> 1 | npm run glossarify +> 2 | npm run glossarify -- --help ## [Configuration Overrides](#configuration-overrides) @@ -27,8 +35,8 @@ Next time you can run [glossarify-md][1] by just typing line 1. Pass arguments a Use Cases -1. Provide a configuration solely via command line -2. Merge a configuration with a config file +1. Provide a [configuration][1] solely via command line +2. Merge a [configuration][1] with a config file **Example:** use `--shallow` to *replace* simple top-level options: @@ -48,4 +56,8 @@ Use Cases --config ./glossarify-md.conf.json --deep "{'glossaries': [{'file':'./extend.md'}] }" -[1]: https://github.com/about-code/glossarify-md "This project." +## [`--watch`](#--watch) + +Watches `baseDir` for changes. + +[1]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md diff --git a/doc/conceptual-layers.md b/doc/conceptual-layers.md index 03340eea..5c7eafe6 100644 --- a/doc/conceptual-layers.md +++ b/doc/conceptual-layers.md @@ -1,35 +1,45 @@ # [Internals: Conceptual Layers](#internals-conceptual-layers) -[doc-syntax-extensions]: ./markdown-syntax-extensions.md + -[remark-gfm]: https://npmjs.com/package/remark-gfm +[Conceptual layers][1] of text processing by [glossarify-md][2] and projects contributing to each layer -[remark-plugins]: https://github.com/remarkjs/awesome-remark +| Layer | Project | Conceptual purpose | +| ----- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 4 | [glossarify-md][2] | [cross-linking][3] multiple markdown files | +| 3 | [unified 🌎][4] | umbrella project for *text file processing in general* | +| 2 | [remark 🌎][5] | [unified 🌎][4] *processor* for *markdown text file processing in particular*. Offers access to an Abstract Syntax Tree ([mdAst 🌎][6]) data structure grown from [micromark 🌎][7] tokens. | +| 1 | [micromark 🌎][7] | remarks internal markdown syntax tokenizer | +| 0 | [CommonMark 🌎][8] | Markdown Syntax Specification | -Conceptual layers of text processing by [glossarify-md][1] and projects contributing to each layer +[glossarify-md][2] is built on [unified 🌎][4], an umbrella project for *text file processing in general*. We use unified with [remark 🌎][5] which in conceptual terms of unified is a *processor* for *Markdown text files in particular*. remark itself is built on (or better *wrapping around*) [micromark 🌎][7] which is a low-level parser/tokenizer operating on a stream of individual character symbols which drive a token state machine. micromark can be considered a technical implementation of the textual [CommonMark 🌎][8] specification. -| Layer | Project | Conceptual purpose | -| ----- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 4 | [glossarify-md][1] | cross-linking multiple markdown files | -| 3 | [unified][2] | umbrella project for *text file processing in general* | -| 2 | [remark][3] | [unified][2] *processor* for *markdown text file processing in particular*. Offers access to an Abstract Syntax Tree ([mdAst][4]) data structure grown from [micromark][5] tokens. | -| 1 | [micromark][5] | remarks internal markdown syntax tokenizer | -| 0 | [CommonMark][6] | Markdown Syntax Specification | +When looking for non-standard [Markdown syntax extensions][9] you should be looking for [remark 🌎][5] [plug-ins][10]. Those plug-ins are likely to depend on and transitively [install][11] their preferred or required [micromark 🌎][7] extension themselves. Others may operate on layer 2 using a simpler RegEx parsing. One plug-in [glossarify-md][2] already installs itself is [remark-gfm 🌎][12] which adds support for the popular [CommonMark 🌎][8] syntax extension [GitHub Flavoured Markdown 🌎][13] (tables, footnotes and more). -[glossarify-md][1] is built on [unified][2], an umbrella project for *text file processing in general*. We use unified with [remark][3] which in conceptual terms of unified is a *processor* for *Markdown text files in particular*. remark itself is built on (or better *wrapping around*) [micromark][5] which is a low-level parser/tokenizer operating on a stream of individual character symbols which drive a token state machine. micromark can be considered a technical implementation of the textual [CommonMark][6] specification. +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md#internals-conceptual-layers "Conceptual layers of text processing by glossarify-md and projects contributing to each layer glossarify-md is built on unified, an umbrella project for text file processing in general." -When looking for non-standard [syntax extensions][doc-syntax-extensions] you should be looking for [remark plug-ins][remark-plugins]. Those plug-ins are likely to depend on and transitively install their preferred or required [micromark][5] extension themselves. Others may operate on layer 2 using a simpler RegEx parsing. One plug-in [glossarify-md][1] already installs itself is [remark-gfm] which adds support for the popular [CommonMark][6] syntax extension [GitHub Flavoured Markdown][7] (tables, footnotes and more). +[2]: https://github.com/about-code/glossarify-md -[1]: https://github.com/about-code/glossarify-md "This project." +[3]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md#cross-linking "ⓘ Since: v5.0.0" -[2]: https://unifiedjs.com "unified is an umbrella project around text file processing in general." +[4]: https://unifiedjs.com "unified is an umbrella project around text file processing in general." -[3]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." +[5]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." -[4]: https://github.com/syntax-tree/mdast "Specification and Implementation of a Markdown Abstract Syntax Tree." +[6]: https://github.com/syntax-tree/mdast "Specification and Implementation of a Markdown Abstract Syntax Tree." -[5]: https://github.com/micromark/ "A low-level extensible implementation of the CommonMark syntax specification (parsing and tokenizing)." +[7]: https://github.com/micromark/ "A low-level extensible implementation of the CommonMark syntax specification (parsing and tokenizing)." -[6]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." +[8]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." -[7]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" +[9]: https://github.com/about-code/glossarify-md/blob/master/doc/markdown-syntax-extensions.md#markdown-syntax-extensions "glossarify-md supports CommonMark and GitHub Flavoured Markdown (GFM)." + +[10]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins.md#installing-and-configuring-plug-ins "The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp." + +[11]: https://github.com/about-code/glossarify-md/blob/master/doc/install.md#install + +[12]: https://npmjs.com/package/remark-gfm "A remark syntax plug-in supporting GitHub Flavoured Markdown." + +[13]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" diff --git a/doc/cross-linking.md b/doc/cross-linking.md new file mode 100644 index 00000000..6bc8b381 --- /dev/null +++ b/doc/cross-linking.md @@ -0,0 +1,158 @@ +# [Cross-Linking](#cross-linking) + +[pandoc-heading-ids]: https://pandoc.org/MANUAL.html#heading-identifiers + +> **ⓘ Since: v5.0.0** + +## [Term-Based Auto-Linking](#term-based-auto-linking) + +[Term-based auto-linking][1] is to assume headings in markdown files called *glossaries* are *terms*. Whenever being mentioned in text the terms are turned into a link to the glossary section where they have been defined. **Since v5.0.0** we have evolved that principle into a more generic means of [cross-linking][2] by supporting [glob 🌎][3] patterns in `glossaries.file`. + +**Example:** + +```json +{ + "glossaries": [ + { "file": "./**/*.md" } + ] +} +``` + +Such a [configuration][4] makes [glossarify-md][5] consider every `*.md` file a *glossary* and each of its section headings *terms*. Mentioning headings (or their [aliases][6]) somewhere in the file turns the phrases into links to that section. You might want to have a look at `linking.*` config options or [Tree-scoped Linking][7] for ways to fine-tune [linkification][8]. + +> **ⓘ** When `glossaries:[]` has multiple `file` entries, each with a glob pattern and the file sets covered by those patterns overlap, then for a file that would be come part of both file sets (intersection) only the entry *latest* in the array applies. + + + +## [Identifier-based Cross-Linking](#identifier-based-cross-linking) + +When there are two or more [term][9] definitions or book sections with the same heading phrase, then you might want to refer to a particular term definition or section, in particular. While we would recommend trying [Term-based Auto-Linking][1] with distinguished *[aliases][6]*, first, there might be situations where you might want to be explicit about a link target. [glossarify-md][5] supports [pandoc's concept of heading identifiers][pandoc-heading-ids] for identifier-based cross linking. + +> **ⓘ Note:** Pandoc's identifier syntax is not standardized in \[CommonMark]. + +**Example: [Identifier-based Cross-Linking][10]** + +*./page1.md* + +```md +## User Story {#s-241} +``` + +The document declares a heading-id `#s-241`. Given `#s-241` is ***unique* across all documents** then you can use it as a link reference in any file being processed... + +```md +[any phrase](#s-241) +``` + +...and [glossarify-md][5] will resolve the actual path to the corresponding section heading for you (relative or absolute based on the `paths` [config option][4]): + +*./pages/page2.md* + + [any phrase](../page1.md#s-241) + +## [Tree-Scoped Linking](#tree-scoped-linking) + +When using term-based auto linking then, occassionally, you might find [term][9] occurrences being linkified in contexts where a link to the respective link target doesn't seem right or even a bit misleading. A manual approach to prevent this in a case-by-case decision is to wrap a term into some HTML-like tag, e.g. `term`. *[Tree-scoped Linking][7]* uses [config option][4] `linking.limitByTermOrigin` to limit the applicable scope of a term definition to a subtree of a file tree and prevent links to other parts of the tree: + +**Example: [Tree-Scoped Linking][7]** + +*Project directory layout:* + + ${ROOT} + |-context-1/ + | |-context-1-1/ + | | |-document.md + | | '-glossary.md + | |-context-1-2/ + | | |-document.md + | | '-glossary.md + | '-glossary.md + | + |-context-2/ + |- ... + '-glossary.md + +*[Configuration][4]* + +```json +{ + "glossaries": [ + {"file": "./**/*.md" } + ], + "linking": { + "limitByTermOrigin": ["parent", "sibling", "self"] + } +} +``` + +A [term][9]'s origin is the glossary section where the term was defined. A link is a directed edge of kind `(term-occurrence) -> (term-origin)`. So... + +```json +"limitByTermOrigin": ["parent", "sibling", "self"] +``` + +...linkifies [term][9] occurrences when the term origin is found to be in the same file, a sibling file in same directory or a file in a direct parent directory (bottom up linking). Given above example, then + +* it *does* link [term][9] occurrences with term definitions in the same file +* it *does* link [term][9] occurrences in `context-1-1` with terms defined in `context-1` or context root `/` +* it *does not* link [term][9] occurrences in context root `/` or `context-1` with terms defined in `context-1-1` +* it *does not* link [term][9] occurrences in `context-1-1` with terms defined in `context-1-2` or `context-2` + +...and so forth, + +```json +"limitByTermOrigin": ["children", "sibling", "self"] +``` + +...linkifies [term][9] occurrences only when the term was defined in the same file a file in the same directory or a file in a subdirectory (top down linking), + +```json +"limitByTermOrigin": ["parent", "children", "sibling", "self"] +``` + +...linkifies [term][9] occurrences in both directions along a filesystem path. Yet, it does not create links between branches of the file tree, e.g. it does not link terms defined in `context-1-2` with term occurrences found in `context-1-1` and vice versa, + +```json +limitByTermOrigin: ["parent", "children", "sibling", "parent-sibling", "self"] +``` + +...linkifies any [term][9] definitions with any term occurrences, including linking accross tree branches (bidirectionally). This is basically the "unlimited" default so is equivalent to `limitByTermOrigin: []`. + +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md#term-based-auto-linking "Term-based auto-linking is to assume headings in markdown files called glossaries are terms." + +[2]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md#cross-linking "ⓘ Since: v5.0.0" + +[3]: https://github.com/isaacs/node-glob#glob-primer "A file pattern matcher." + +[4]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md + +[5]: https://github.com/about-code/glossarify-md + +[6]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md#aliases "Expects a comma-separated string or a list of strings which provide synonyms or alternative spellings for a term that should be linked with a term definition when found in text." + +[7]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md#tree-scoped-linking "When using term-based auto linking then, occassionally, you might find term occurrences being linkified in contexts where a link to the respective link target doesn't seem right or even a bit misleading." + +[8]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#linkification "Process of searching for a term in document A matching a heading phrase in +document B and replacing the term in document A with a Markdown link pointing +onto the term definition in document B." + +[9]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#term "Terms are headings in a markdown file which has been configured to be a glossary file." + +[10]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md#identifier-based-cross-linking "When there are two or more term definitions or book sections with the same heading phrase, then you might want to refer to a particular term definition or section, in particular." diff --git a/doc/export.md b/doc/export.md new file mode 100644 index 00000000..1d7d5ef0 --- /dev/null +++ b/doc/export.md @@ -0,0 +1,53 @@ +# [Export](#export) + + + +**Since v6.0.0** + +[Exporting][1] makes [glossarify-md][2] generate and write a structured representation of a markdown glossary to the output directory. + +## [JSON (SKOS RDF/JSON-LD)](#json-skos-rdfjson-ld) + +*Example: [Export][1] terms in glossary.md as ./glossary.json* + +```json +{ + "glossaries": [{ + "uri": "http://basic.org/vocabulary/#", + "file": "./glossary.md", + "export": { + "file": "./glossary.json" + } + }] +} +``` + +> **ⓘ** We recommend declaring a glossary `uri` when exporting. It will make glossarify-md assign each term a unique *uniform resource identifier* by combining the URI with a term's term identifier. +> +> More on the idea behind URIs read Vocabulary URIs. See config option `headingIdAlgorithm` to select an algorithm for generating term identifiers from the term itself. Use pandoc syntax `{#my-own-id}` in a term heading to specify your own term identifier. + +## [RDF/N-Quads](#rdfn-quads) + +With [jsonld 🌎][3] installed alongside [glossarify-md][2] terms can also be exported to RDF N-Quads (file extension `.nq`). + +*Example: [Export][1] terms in glossary.md as ./glossary.nq* + +```json +{ + "glossaries": [{ + "uri": "http://basic.org/vocabulary/#", + "file": "./glossary.md", + "export": { + "file": "./glossary.nq" + } + }] +} +``` + +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/export.md#export "Since v6.0.0 Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory." + +[2]: https://github.com/about-code/glossarify-md + +[3]: https://npmjs.com/package/jsonld "A JavaScript implementation of JSON-LD." diff --git a/doc/gen-book-index.md b/doc/gen-book-index.md new file mode 100644 index 00000000..a65c2d43 --- /dev/null +++ b/doc/gen-book-index.md @@ -0,0 +1,46 @@ +## [Generating Files: Book Index](#generating-files-book-index) + +[doc-lists]: ./gen-lists.md + +*[glossarify-md][1].conf.json* + +```json +"generateFiles": { + "indexFile": { + "file": "./book-index.md", + "title": "Book Index" + } +} +``` + +This option will generate a single book index file `./book-index.md` with glossary terms and links to book sections in which they have been mentioned. By default items will be grouped *by section of occurrence* using the section heading as a group title. You can disable or affect granularity of section-based grouping using: + +```json +"indexing": { + "groupByHeadingDepth": 0 +} +``` + +> **ⓘ Note**: The `groupByHeadingDepth` option also affects grouping of list items in [Lists][doc-lists]. + +Let's assume you have multiple glossaries and you want to create separate book indexes from terms of those glossaries. **Since v5.1.0** you can use `indexFiles` (plural) like this: + +```json +"generateFiles": { + "indexFiles": [{ + "title": "Book Index for Glossary 1", + "file": "./book-index-1.md", + "glossary": "./glossary-1.md" + },{ + "title": "Book Index for Glossary 2", + "file": "./book-index-2.md", + "glossary": "./glossary-2.md" + }] +} +``` + +> **ⓘ Note:** If you plan on translating markdown to HTML, e.g. with [vuepress][2], be aware that a file `index.md` will translate to `index.html` which is typically reserved for the default HTML file served under a domain. We recommend you choosing another name. + +[1]: https://github.com/about-code/glossarify-md + +[2]: https://vuepress.vuejs.org diff --git a/doc/gen-lists.md b/doc/gen-lists.md new file mode 100644 index 00000000..d9676e21 --- /dev/null +++ b/doc/gen-lists.md @@ -0,0 +1,288 @@ +### [Generating Files: Lists](#generating-files-lists) + +[CommonMark]: https://commonmark.org + +[GFM]: https://github.github.com/gfm/ + +You can generate **arbitrary lists from HTML elements with an `id` attribute** and an element *classifier* to compile similar elements into the same list. + + +*Example: Markdown document with a video element* + +```md +More details see our video tutorial: + + +``` + +Then to generate a *[List of Videos][1]* from all elements of `class="video"` add to your *[glossarify-md][2].conf.json*: + +```json +"generateFiles": { + "listOf": [{ + "class": "video", + "title": "List of Videos", + "file": "./videos.md" + }] +} +``` + +After running [glossarify-md][2] there will be a file: + +*docs-glossarified/videos.md (generated)* + +> ## [List of Videos](#list-of-videos) +> +> * [Tutorial Part 1][3] + +You can **type less** when prefixing ids with your list classifier: + +```md + +``` + +Without a `title` attribute the tool attempts to derive a list item label from an elements inner text content: + +```md + +``` + +Use *invisible* HTML anchors to generate lists from and navigate to text content: + +```md + +This is not a video tutorial but a textual tutorial. The body of text can be navigated to from a List of Tutorials and uses the classifier *tutorial*. +``` + +> **ⓘ Note:** If you find the browser not scrolling correctly when navigating lists on GitHub, please read [Known Issues: Lists in GitHub Repos][4]. + + + +### [List of Figures](#list-of-figures) + +In the previous section we used [`listOf`][5] to generate a list *from HTML elements* inside Markdown. Writing HTML can be annoying, particularly if there is handier Markdown syntax for the elements to be listed. This is where `listOfFigures` and [`listOfTables`][6] fit in. It is a shortcut which makes [glossarify-md][2] generate the HTML anchor itself from Markdown's image syntax: + +```md +![List item Label](./figure.png) +``` + +Then you may only need to use HTML for dynamically rendered figures, e.g. a [PlantUML 🌎][7] diagram: + +````md +
Dynamically Rendered Diagram
+ +```plantuml +@startuml +... your PlantUML diagram code ... +@enduml +``` +```` + +To compile both figures into the same list one way to configure [glossarify-md][2] is to declare a `listOf` class *figure* (for HTML elements) and tell `listOfFigures` (for `![]()` images) to use the same classifier *figure*: + +*[glossarify-md][2].conf.json* (since v5.0.0) + +```json +"generateFiles": { + "listOf": [{ + "class": "figure", + "title": "List of Figures", + "file": "./figures.md" + }], + "listOfFigures": { + "class": "figure" + } +} +``` + +This [configuration][8] which would allow you to also choose a shorter classifier like *fig* is the default, though. Therefore, if you are fine with ***figure* as the default classifier** you can omit `listOf` and just use: + +*[glossarify-md][2].conf.json* + +```json +"generateFiles": { + "listOfFigures": { + "title": "List of Figures", + "file": "./figures.md" + } +} +``` + +### [List of Tables](#list-of-tables) + +`listOfTables` like [`listOfFigures`][9] is a shortcut alternative to HTML anchors with a default [`listOf`][10] classifier ***table***: + +*[glossarify-md][2].conf.json* + +```json +"generateFiles": { + "listOfTables": { + "title": "Tables", + "file": "./tables.md" + } +} +``` + +In contrast to images Markdown tables have no notion of a table caption. To render a list item for a table [glossarify-md][2] tries to infer a list item label. + +One such inference looks at the **paragraph preceding the table**. If it **ends with an *emphasized* phrase** and the phrase itself is **terminated by a colon** then the tool uses that phrase as the item label: + + + +```md +[...] which we can see from the *table of average prices by article category:* + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +But the phrase could also be it's own distinct paragraph: + +```md +[...] which we can see from the average price by article category. + +*Average prices by category:* + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +**Since v3.4.0** there has also been support for *invisble* table captions using *HTML comment syntax*: + +```md + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +The result for the tables above will be: + +> ## [List of Tables](#list-of-tables-1) +> +> * [Table of average prices by article category][11] +> * [Average prices by category][12] +> * [Average Prices by Article Category][13] + +**Since v5.0.0** and the introduction of [`listOf`][5] all the previous examples will make [glossarify-md][2] annotate the table with an HTML anchor. While not recommended due to verbosity, you could also just add an HTML anchor yourself, of course, applying what was described in [`listOf`][5] above: + +```md + + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +> **ⓘ Note:** If glossarify-md can't find a list item label by any of the above means it will fall back to rendering a list item +> +> 1. using the table headers separated by comma, +> 2. or if no headers, using the closest section heading +> 3. or if no section heading, using the file name. + + + +### [Lists from Regular Expressions (Experts)](#lists-from-regular-expressions-experts) + +**Since v5.2.0** you can use `listOf` with a regular expression pattern. Like [`listOfFigures`][9] and [`listOfTables`][6] it is meant to be a shortcut to save you from annotating Markdown with HTML elements yourself. If the regular expression (RegExp) matches text in a paragraph, then *the paragraph* will become annotated with an HTML anchor `` preparing it for evaluation by `listOf` as we have seen above. + +**Example:** Let's assume you are writing a book with *tasks* to be accomplished by your readers. You would like to compile a *List of Tasks* in that book. You decided to use a conventional pattern which prefixes tasks with a phrase **Task:** and ends them with an exclamation mark *!* + +*Document.md* + +```md +Some text [...] + +**Task:** Clap your hands! +``` + +Then you can generate a *List of Tasks* with a [configuration][8] like this: + +```md +{ + "generateFiles": { + "listOf": [ + { + "class": "task", + "title": "Tasks in this Book", + "file": "./list-of-tasks.md", + "pattern": "Task: ([a-zA-Z0-9].*)!" + } + ] + } +} +``` + +Our expression uses a Capture Group in brackets `()`. Text matching the capture group pattern will become the list item label, so *Clap your hands* will become the item label, because `Task:` and exclamation mark `!` are not part of the group. There can be at most one capture group. + +> **ⓘ When to consider "Markdown" syntax in the RegExp pattern?**: +> +> You may noticed that the RegExp pattern above doesn't assume *Task:* to be written between "bold" star markers `**`, even though, that's the case in the input file *Document.md*. The pattern will be matched against *plain text* that was separated from syntactic tokens of [CommonMark] and [GFM] syntax. Other *non-standard* markdown syntax may require a special syntax plug-in which parses its tokens into an abstract syntax tree. Otherwise they will be considered plain text, too, thus have to be considered in the RegExp pattern. Unfortunately, remark plug-ins behave differently in this regard. There are plug-ins which promote special syntax which fits *their* purpose, yet *without* correctly parsing their syntax into an abstract syntax tree. So if this feature causes you headaches better try both ways or consider it not fit for your purpose. + +See also page [Plug-ins][14]. + +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/gen-lists.md#list-of-videos "Tutorial Part 1 You can type less when prefixing ids with your list classifier: Without a title attribute the tool attempts to derive a list item label from an elements inner text content: Use invisible HTML anchors to generate lists from and navigate to text content: ⓘ Note: If you find the browser not scrolling correctly when navigating lists on GitHub, please read Known Issues: Lists in GitHub Repos." + +[2]: https://github.com/about-code/glossarify-md + +[3]: #video-tutorial-part-1 + +[4]: https://github.com/about-code/glossarify-md/blob/master/doc/lists-on-github.md + +[5]: https://github.com/about-code/glossarify-md/blob/master/doc/gen-lists.md#generating-files-lists "You can generate arbitrary lists from HTML elements with an id attribute and an element classifier to compile similar elements into the same list." + +[6]: https://github.com/about-code/glossarify-md/blob/master/doc/gen-lists.md#list-of-tables "listOfTables like listOfFigures is a shortcut alternative to HTML anchors with a default listOf classifier table: glossarify-md.conf.json In contrast to images Markdown tables have no notion of a table caption." + +[7]: https://plantuml.com "Generates diagrams from text files written in the PlantUML syntax." + +[8]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md + +[9]: https://github.com/about-code/glossarify-md/blob/master/doc/gen-lists.md#list-of-figures "In the previous section we used listOf to generate a list from HTML elements inside Markdown." + +[10]: #lists + +[11]: #table-of-average-prices-by-article-category + +[12]: #average-prices-by-category + +[13]: #avg-prices + +[14]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins.md#installing-and-configuring-plug-ins "The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp." diff --git a/doc/glossary.md b/doc/glossary.md index 3d077a09..004c585b 100644 --- a/doc/glossary.md +++ b/doc/glossary.md @@ -1,29 +1,27 @@ -# [Glossary](#glossary) +# [Glossary (Terms and Concepts of glossarify-md)](#glossary-terms-and-concepts-of-glossarify-md) -[glossarify-md]: https://github.com/about-code/glossarify-md - -This is a glossary of terms helpful when working with [glossarify-md] or reading its docs. It also serves as an example and is processed by *[glossarify-md][1]* itself using the [glossarify-md.conf.json][2] configuration at the root of this repo. +This is a glossary of terms helpful when working with [glossarify-md][1] or reading its docs. It also serves as an example and is processed by glossarify-md itself using the [glossarify-md.conf.json][2] [configuration][3] at the root of this repo. ## [Alias](#alias) -An alternative [term★][3] or spelling for a term. +An alternative [term][4] or spelling for a term. ## [Term](#term) -A [term★][3] is denoted by a heading in a markdown file which is told [glossarify-md][1] to be a *glossary file*. +Terms are headings in a markdown file which has been configured to be a *glossary file*. ## [Term Attribute](#term-attribute) -[Term★][3] Attributes are passed in a comment following a term's heading. The comment must adhere to YAML syntax. +[Term][4] Attributes are passed in a comment following a term's heading. The comment must adhere to YAML syntax. ## [Term Hint](#term-hint) -An optional (symbol-) character like for example `↴` decorating a [term★][3] link to distinguish it from a regular link. -See [glossarify-md][1] configuration options for details. +An optional (symbol-) character like for example `↴` decorating a [term][4] link to distinguish it from a regular link. +See [glossarify-md][1] [configuration][3] options for details. ## [Vocabulary](#vocabulary) @@ -35,7 +33,7 @@ A collection of terms which is uniquely identifiable. See also [Semantic Web Voc ## [Linkification](#linkification) -Process of searching for a [term★][3] in *document A* matching a heading phrase in +Process of searching for a [term][4] in *document A* matching a heading phrase in *document B* and replacing the term in *document A* with a Markdown link pointing onto the term definition in *document B*. @@ -43,13 +41,13 @@ onto the term definition in *document B*. -A [slug★][4] is a URL-friendly identifier that can be used within [URL fragments★][5] to address headings / sections on a page. +A [slug][5] is a URL-friendly identifier that can be used within [URL fragments][6] to address headings / sections on a page. ## [URL fragment](#url-fragment) -The fragment is the part follwing the `#` in a [URL★][6]. +The fragment is the part follwing the `#` in a [URL][7]. ## [URI / URL](#uri--url) @@ -61,26 +59,28 @@ The fragment is the part follwing the `#` in a [URL★][6]. -Glossaries are considered a kind of *Knowledge Organisation System ([KOS★][7])* which organizes knowledge as a list of terms and [term★][3] definitions. There are other KOS like *Thesauri*, *Taxonomies* or *Word Nets* which add term relationships (hierarchically or as graphs capturing semantic or linguistic relationships). To model informal KOS the W3C has developed [SKOS][8]. +Glossaries are considered a kind of *Knowledge Organisation System ([KOS][8])* which organizes knowledge as a list of terms and [term][4] definitions. There are other KOS like *Thesauri*, *Taxonomies* or *Word Nets* which add term relationships (hierarchically or as graphs capturing semantic or linguistic relationships). To model informal KOS the W3C has developed [SKOS 🌎][9]. -[Formal Ontologies★][9] are graph-like [KOS★][7] which focus on *logical formalism*. They are built from logical statements and tend to become harder to maintain as they grow due to a requirement of being *fully free of logical conflicts*. Ontologies require a (meta-) vocabulary known as the *Web Ontology Language* [OWL][10]. [SKOS][8] was built on top of OWL. +[Formal Ontologies][10] are graph-like [KOS][8] which focus on *logical formalism*. They are built from logical statements and tend to become harder to maintain as they grow due to a requirement of being *fully free of logical conflicts*. Ontologies require a (meta-) vocabulary known as the *Web Ontology Language* [OWL 🌎][11]. [SKOS 🌎][9] was built on top of OWL. -[1]: https://github.com/about-code/glossarify-md "This project." +[1]: https://github.com/about-code/glossarify-md [2]: ../glossarify-md.conf.json -[3]: #term "A term is denoted by a heading in a markdown file which is told glossarify-md to be a glossary file." +[3]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md + +[4]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#term "Terms are headings in a markdown file which has been configured to be a glossary file." -[4]: #slug "A slug is a URL-friendly identifier that can be used within URL fragments to address headings / sections on a page." +[5]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#slug "A slug is a URL-friendly identifier that can be used within URL fragments to address headings / sections on a page." -[5]: #url-fragment "The fragment is the part follwing the # in a URL." +[6]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#url-fragment "The fragment is the part follwing the # in a URL." -[6]: #uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." +[7]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." -[7]: #kos---knowledge-organization-systems "Glossaries are considered a kind of Knowledge Organisation System (KOS) which organizes knowledge as a list of terms and term definitions." +[8]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#kos---knowledge-organization-systems "Glossaries are considered a kind of Knowledge Organisation System (KOS) which organizes knowledge as a list of terms and term definitions." -[8]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets." +[9]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets." -[9]: #vocabulary "A collection of terms which is uniquely identifiable." +[10]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#vocabulary "A collection of terms which is uniquely identifiable." -[10]: https://www.w3.org/TR/2012/REC-owl2-overview-20121211/ "Web Ontology Language." +[11]: https://www.w3.org/TR/2012/REC-owl2-overview-20121211/ "Web Ontology Language." diff --git a/doc/import.md b/doc/import.md new file mode 100644 index 00000000..2d226833 --- /dev/null +++ b/doc/import.md @@ -0,0 +1,147 @@ +# [Importing Terms](#importing-terms) + + + +[strip-markdown]: https://npmjs.com/package/strip-markdown + +> **⚠ Important:** glossarify-md is able to import terms and definitions from a remote location using `https`. It will try to remove any Markdown and HTML from imported data using [strip-markdown][strip-markdown]. Nevertheless, as a rule of thumb, **never import from untrusted sources**. +> +>
+> Loading files from a remote location could enable a remote entity to embed malicious code, execute such code in the runtime context of glossarify-md or make glossarify-md embed it into your output files. Consider downloading files first and after review import them statically from within your project. + +
+ +*** + +### [From CSV](#from-csv) + +**Since v6.4.0** + +CSV is a textual serialization for tabular data and supported by most spreadsheed programmes. Columns in CSV are separated by a `delimiter`. + +*Example: CSV formatted tabular data delimited by `;` and without a header row* + +```csv +#123;IGNORED-COLUMN;My Term;Alternative Term;This Term stands for Foo +``` + +Without a header row embedded into the CSV data a `schema` mapping is required to tell [glossarify-md][1] where to find glossary columns (resp. `fields`): + +```json +{ + "...": "..." + "glossaries": [{ + "uri": "http://your-domain.com/vocab/#", + "file": "./glossary.md", + "import": { + "file": "./terms.csv", + "dialect": { + "delimiter": ";", + "doubleQuotes": true + }, + "schema": { + "fields": [ + { "name": "@id"}, + { "name": "" }, + { "name": "http://www.w3.org/2004/02/skos/core#prefLabel" }, + { "name": "http://www.w3.org/2004/02/skos/core#altLabel" }, + { "name": "http://www.w3.org/2004/02/skos/core#definition" } + ] + } + }] +} +``` + +* Use `@id` for the ID column +* Use [http://www.w3.org/2004/02/skos/core#prefLabel][2] for the [term][3] column +* Use [http://www.w3.org/2004/02/skos/core#altLabel][4] for one or more alternative [term][3] columns ([aliases][5]) +* Use [http://www.w3.org/2004/02/skos/core#definition][6] for the [term][3] definition column + +A `schema` mapping can be omitted when the CSV file embeds these as header labels in the first row: + +*Example: CSV with a header row* + +```csv +@id;http://www.w3.org/2004/02/skos/core#prefLabel;http://www.w3.org/2004/02/skos/core#altLabel;http://www.w3.org/2004/02/skos/core#definition + +#123;My Term;Alternative Term;This Term stands for Foo +``` + +### [From JSON (glossarify-md exports)](#from-json-glossarify-md-exports) + +**Since v6.0.0** + +```json +{ + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./terms.json" + } + }] +} +``` + +### [From JSON (arbitrary)](#from-json-arbitrary) + +```json +{ + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./terms.json", + "context": "./mapping.jsonld" + } + }] +} +``` + +[Importing][7] from arbitrary data models and JSON serializations is likely to require mappings onto [SKOS 🌎][8] types and attributes. See Interoperability with SKOS and [JSON-LD 🌎][9] for an in-depth example. + +### [From RDF + SKOS](#from-rdf--skos) + +**Since v6.0.0** + +If you have an [SKOS 🌎][8] description of a glossary or taxonomy stored in some RDF [linked data 🌎][10] store then you might find linked data tooling that is able to [export][11]/convert/serialize your linked data [vocabulary][12] to **N-Triples, N-Quads or [JSON-LD 🌎][9]**. + +* [Importing][7] from [JSON-LD 🌎][9] should work similar to importing [glossarify-md][1]'s own JSON [exports][11] +* [Importing][7] N-Triples/N-Quads requires the file name to end with `.nq` + +*Example: [Import][7] RDF + [SKOS 🌎][8] from an N-Quads serialization:* + +```json +{ + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./terms.nq" + } + }] +} +``` + +[1]: https://github.com/about-code/glossarify-md + +[2]: http://www.w3.org/2004/02/skos/core#prefLabel + +[3]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#term "Terms are headings in a markdown file which has been configured to be a glossary file." + +[4]: http://www.w3.org/2004/02/skos/core#altLabel + +[5]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md#aliases "Expects a comma-separated string or a list of strings which provide synonyms or alternative spellings for a term that should be linked with a term definition when found in text." + +[6]: http://www.w3.org/2004/02/skos/core#definition + +[7]: https://github.com/about-code/glossarify-md/blob/master/doc/import.md#importing-terms "⚠ Important: glossarify-md is able to import terms and definitions from a remote location using https." + +[8]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets." + +[9]: https://json-ld.org "JSON-LD is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public vocabularies." + +[10]: https://www.w3.org/standards/semanticweb/ontology "See Linked Data." + +[11]: https://github.com/about-code/glossarify-md/blob/master/doc/export.md#export "Since v6.0.0 Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory." + +[12]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#vocabulary "A collection of terms which is uniquely identifiable." diff --git a/doc/install.md b/doc/install.md new file mode 100644 index 00000000..8deecb99 --- /dev/null +++ b/doc/install.md @@ -0,0 +1,36 @@ +# [Install](#install) + +### [Option 1: Install *locally*, init, configure, run:](#option-1-install-locally-init-configure-run) + + cd ./your-project + npm install glossarify-md + + npx glossarify-md --init --new --local + npx glossarify-md --config ./glossarify-md.conf.json + +When installing locally you might want to set up a shortcut by adding a run script to your `package.json`: + +```json +{ + "scripts": { + "glossarify": "glossarify-md --config ./glossarify-md.conf.json" + } +} +``` + +Now use: + + npm run glossarify + +### [Option 2: Install *globally*, init, configure, run:](#option-2-install-globally-init-configure-run) + + npm install -g glossarify-md + + glossarify-md --init --new + glossarify-md --config ./glossarify-md.conf.json + +> **ⓘ** Many editors and IDEs use a `$schema` configuration schema declaration to provide you with assistance in editing a JSON config file. Installing glossarify-md globally will require `$schema` to point to a configuration schema hosted on GitHub. That schema refers to the version that has been used when the configuration file was created, initially. Later, when updating the global installation of glossarify-md pointers in your project configurations won't be updated and continue to point the config schema version at initialization time. This is not an issue at all. Just note that editors won't suggest newer options from the latest globally installed release unless you update the `$schema` url to match the config schema version that is in line with the current install. However you'll receive a command line hint when glossarify-md detects such a situation. + +See also page [Configuration][1]. + +[1]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md diff --git a/doc/lists-on-github.md b/doc/lists-on-github.md index bd11aa8a..b4f70a92 100644 --- a/doc/lists-on-github.md +++ b/doc/lists-on-github.md @@ -1,45 +1,57 @@ # [Known Issues: Lists in GitHub Repos](#known-issues-lists-in-github-repos) -[doc-readme-lists]: ../README.md#lists + -[gfm-sanitize]: https://github.github.com/gfm/#what-is-github-flavored-markdown- +[2]: #large-file-link-target -[gh-pages]: https://pages.github.com/ +**Note:** This issue may only affect you or your readers -[html-sem-tags]: https://www.w3schools.com/html/html5_semantic_elements +1. when navigating GitHub *previews* of Markdown files within a GitHub repository +2. when navigating from a list item generated with the `listOf` [config option][1] to a link target that requires the browser to scroll the link target into the visible viewport -[2]: <> +The issue is: \*the browser may not scroll the link target into the visible viewport as expected. -Addendum to [Section *Lists* in README.md][doc-readme-lists] +## [Reproduction of the Issue](#reproduction-of-the-issue) -We assume you have generated a `list.md` file using a `listOf` config: +Let's imagine such a GitHub repository. It has a file `README.md` that has a lot of text and some addressable HTML element `` quite at the bottom of that page: -> ## [My List](#my-list) -> -> * [List item title][2] + *README.md* -The list item was generated from a document with an element + ~~~md + ... lot's of text here... + Some Magazine Title + ~~~ -```md -... lot's of text here... -List item title -``` +* ...to have a file `list.md` generated using `listOf` with `class: "citations"`: -where `cite` is at the bottom of a larger file `page.md` and, initially, *out of the visible viewport* of a browser. -Normally, when converting such markdown to HTML using a Markdown-to-HTML static page renderer you would expect the list item link to be a link which targets the document *but also* make the browser scroll to make the targeted section part of the visible viewport. + *list.md* -On a GitHub repository, though, you'll find that you can navigate within the repository using the list item link in `list.md` but the browser *won't* scroll to the item position `#mylist-foo` in `page.md`. The reason for this is that GitHub *[sanitizes][gfm-sanitize]* Markdown files before rendering them within their own repository previews. They allow only a small subset of HTML and strip elements like `` and other [Semantic HTML Tags][html-sem-tags] including the element's `id="#mylist-foo"` which a browser needs to be able to scroll to that part of an HTML document. Therefore, if you care for navigability in GitHub repositories, just use supported elements like `` or `` instead. + ```md + ## [Citations](#my-list) -**This is a limitation of GitHub's repository preview renderer *only*!** It is not a bug in [glossarify-md][3]. For example, if you were rendering `list.md` and `page.md` with a static website generator like [Jekyll][4] or [vuepress][5] things work just fine. + * [Some Magazine Title][2] -You can even try yourself with [GitHub Pages][gh-pages] which renders `.md` files in a repo to [https://yoursite.github.io][6] using [Jekyll][4]. + [2]: ./README.md#some-magazine + ``` -[1]: #my-list +Then you browse the repository in the web browser enjoying GitHubs preview of Markdown files in the repo. You would like to navigate from `list.md` to `./README.md#some-magazine` by clicking the list item link generated by [glossarify-md][3]. You'd expect your browser to *scroll* to the link target quite at the bottom of `page.md` *but it doesn't!* -[3]: https://github.com/about-code/glossarify-md "This project." +## [Root Cause](#root-cause) -[4]: https://jekyllrb.com "A static website renderer compiling an HTML website from Markdown files." +**GitHub sanitizes Markdown files** (see [GFM 🌎][4] Sect.1.1) before HTML-rendering them within repository previews. It does so to safeguard GitHub users from evil repository owners who attempt to embed scripts and harmful content into markdown and make that content execute in a victims browser while it browses GitHub. To prevent that GitHub only allows for a small subset of the most commonly used and safe HTML tags and strips others. `` is among those that *are* stripped. The browser therefore can't find that element in the Markdown preview and consequently can't scroll to it. -[5]: https://vuepress.vuejs.org "A static website generator translating markdown files into a website powered by [vuejs]." +## [Workaround](#workaround) -[6]: https://yoursite.github.io +If you care for navigability in GitHub repositories only use HTML tags like `` or `` that aren't stripped in GitHub repository previews. + +**Note that this is a limitation of GitHub's repository preview renderer *only*!** It is not a bug in [glossarify-md][3] and once you use a static website generator to generate HTML files from Markdown in order to host them on [GitHub Pages 🌎][5] or your own webserver, things will work just fine. It's just when navigating GitHub *previews* of Markdown files where things may not work as you would expect them to do. + +[1]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md + +[3]: https://github.com/about-code/glossarify-md + +[4]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" + +[5]: https://pages.github.com/ "GitHub Pages is a static website rendering and publishing service by GitHub Inc." diff --git a/doc/markdown-syntax-extensions.md b/doc/markdown-syntax-extensions.md index 12c2d69f..091153ec 100644 --- a/doc/markdown-syntax-extensions.md +++ b/doc/markdown-syntax-extensions.md @@ -1,18 +1,10 @@ # [Markdown Syntax Extensions](#markdown-syntax-extensions) -[doc-conceptual-layers]: ./conceptual-layers.md + -[doc-plugins]: ./plugins.md - -[doc-plugins-dev]: ./plugins-dev.md - -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter - -[remark-plugins]: https://github.com/remarkjs/awesome-remark - -[unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md - -[glossarify-md][1] supports [CommonMark][2] and [GitHub Flavoured Markdown][3] (GFM). Syntax not covered by these specifications may have no or worse, a wrong representation in the tool's Abstract Syntax Tree ([mdAst][4]). As a consequence it may not make it correctly into output documents. For example *Frontmatter* syntax is a Markdown syntax extension popularized by many static site generators: +[glossarify-md][1] supports [CommonMark 🌎][2] and [GitHub Flavoured Markdown 🌎][3] (GFM). Syntax not covered by these specifications may have no or worse, a wrong representation in the tool's Abstract Syntax Tree ([mdAst 🌎][4]). As a consequence it may not make it correctly into output documents. For example *Frontmatter* syntax is a Markdown syntax extension popularized by many static site generators: *Frontmatter Syntax* @@ -20,11 +12,11 @@ key: This is a frontmatter --- -Without special support for it [CommonMark][2] compliant parsers like our [remark][5] parser will interpret the line of trailing dashes as *heading* markers and the text before them as *heading text*. So to make our parser aware of frontmatter syntax we need to enhance it. +Without special support for it [CommonMark 🌎][2] compliant parsers like our [remark 🌎][5] parser will interpret the line of trailing dashes as *heading* markers and the text before them as *heading text*. So to make our parser aware of frontmatter syntax we need to enhance it. -**Since v5.0.0** we have opened [glossarify-md][1] to the [remark plug-in ecosystem][remark-plugins] and its support of additional syntaxes and tools. More see [Installing Plug-ins][doc-plugins] and [Writing a Plug-in][doc-plugins-dev]. +**Since v5.0.0** we have opened [glossarify-md][1] to the [remark 🌎][5] [plug-in ecosystem 🌎][6] and its support of additional syntaxes and tools. More see [Installing Plug-ins][7] and [Writing a Plug-in][8]. -[1]: https://github.com/about-code/glossarify-md "This project." +[1]: https://github.com/about-code/glossarify-md [2]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." @@ -33,3 +25,9 @@ Without special support for it [CommonMark][2] compliant parsers like our [remar [4]: https://github.com/syntax-tree/mdast "Specification and Implementation of a Markdown Abstract Syntax Tree." [5]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." + +[6]: https://github.com/remarkjs/awesome-remark "A curated list of remark plug-ins." + +[7]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins.md#installing-and-configuring-plug-ins "The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp." + +[8]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins-dev.md#writing-a-plug-in diff --git a/doc/paths-and-urls.md b/doc/paths-and-urls.md index da57590d..7da04aeb 100644 --- a/doc/paths-and-urls.md +++ b/doc/paths-and-urls.md @@ -1,6 +1,6 @@ # [Paths and URLs](#paths-and-urls) -When using [glossarify-md][1] with a static website renderer it may be necessary to tweak links and link paths generated by glossarify-md. There are quite a few `linking` options which affect how links will be generated. They'll be explained in a bit more detail here: +When using [glossarify-md][1] with a static website renderer it may be necessary to tweak links and [link paths][2] generated by glossarify-md. There are quite a few `linking` options which affect how links will be generated. They'll be explained in a bit more detail here: ## [`paths` and `baseUrl`](#paths-and-baseurl) @@ -22,14 +22,14 @@ When using [glossarify-md][1] with a static website renderer it may be necessary One thing which the previous options do not care for are file extensions. For example [glossarify-md][1] will keep the `.md` file extension in output files assuming that any post processor should expect markdown files to link each other using that file extension. -However, some static website renderers or translators like [pandoc][2] are able to translate Markdown to HTML but forget about changing file extensions present in links: +However, some static website renderers or translators like [pandoc 🌎][3] are able to translate Markdown to HTML but forget about changing file extensions present in links: * Use `pathComponents: ["path", "file"]` and omit `"ext"` to drop the file extension * Use `pathRewrites: { ".html": ".md" }` to change the file extension ### [Path Rewriting](#path-rewriting) -If your post processor moves files around but is not able to properly adjust link paths, then you may whish [glossarify-md][1] to produce paths which resemble the final structure rather than the output structure created by glossarify-md. +If your post processor moves files around but is not able to properly adjust [link paths][2], then you may whish [glossarify-md][1] to produce paths which resemble the final structure rather than the output structure created by glossarify-md. **Rules of thumb**: @@ -50,6 +50,8 @@ If your post processor moves files around but is not able to properly adjust lin You can use anything acceptable to JavaScript's `String.replace()` method. Just note that in the rewrite map *keys are the replacer* and *values are one or more search expressions* (including regular expressions). -[1]: https://github.com/about-code/glossarify-md "This project." +[1]: https://github.com/about-code/glossarify-md -[2]: https://pandoc.org "See pandoc." +[2]: https://github.com/about-code/glossarify-md/blob/master/doc/use-with-hugo.md#link-paths "Hugo has its own means of producing website URLs from a project's filesystem." + +[3]: https://pandoc.org "See pandoc." diff --git a/doc/plugins-dev.md b/doc/plugins-dev.md index c3319011..409aebcd 100644 --- a/doc/plugins-dev.md +++ b/doc/plugins-dev.md @@ -1,24 +1,20 @@ # [Writing a Plug-In](#writing-a-plug-in) -[doc-conceptual-layers]: ./conceptual-layers.md - -[mdast-util-visit]: https://npmjs.com/package/mdast-util-visit + [remark-discussion]: https://github.com/remarkjs/remark/discussions/869#discussioncomment-1602674 -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter - -[verdaccio]: https://npmjs.com/package/verdaccio - ## [Syntax Plug-Ins](#syntax-plug-ins) -Syntax Plug-ins extend Markdown syntax itself, like [remark-frontmatter], for example. They contribute new *node types* to an internal Abstract Syntax Tree (AST). Further they provide a tokenizer to parse and a serializer to write markdown files. Writing syntax plug-ins is a bit more elaborate. At this point we like to refer you to the documentation of [micromark][1] and [mdAst][2]. When exploring these projects you might find this [description of the overall process][remark-discussion] helpful. +[Syntax Plug-ins][1] extend Markdown syntax itself, like [remark-frontmatter 🌎][2], for example. They contribute new *node types* to an internal Abstract Syntax Tree (AST). Further they provide a tokenizer to parse and a serializer to write markdown files. Writing syntax [plug-ins][3] is a bit more elaborate. At this point we like to refer you to the documentation of [micromark 🌎][4] and [mdAst 🌎][5]. When exploring these projects you might find this [description of the overall process][remark-discussion] helpful. ## [Tree-Plug-Ins](#tree-plug-ins) -*Tree plug-ins* operate on a markdown syntax tree ([mdAST][2]). They are much easier to write and use [CommonMark][3] and [GFM][4] syntax and respective AST node types to do their job. Basically they inspect, add, remove or resort AST nodes. [glossarify-md][5] operates on tree plug-ins, almost only (see [Conceptual Layers][doc-conceptual-layers]). +*Tree [plug-ins][3]* operate on a markdown syntax tree ([mdAST 🌎][5]). They are much easier to write and use [CommonMark 🌎][6] and [GFM 🌎][7] syntax and respective AST node types to do their job. Basically they inspect, add, remove or resort AST nodes. [glossarify-md][8] operates on tree plug-ins, almost only (see page [Conceptual Layers][9]). -A tree plug-in is a function which returns a callback that when called get's passed an [mdAst][2] root node (`tree`): +A tree plug-in is a function which returns a callback function. The callback function receives an [mdAst 🌎][5] node (usually the root node for a markdown file) whose subtree can be inspected and modified by visiting all or particular types of nodes: *remark-my-plug-in.js* @@ -40,10 +36,10 @@ export default function myPlugin(options = {}) { } ``` -The example simply adds a `&visited=true` [URL★][6] query parameter to each Markdown link in a document. +The example simply adds a `&visited=true` [URL][10] query parameter to each Markdown link in a document. -It uses a [visit][mdast-util-visit] utility function with a filter argument (2) and visitor callback argument (3). The filter argument can be the name of a node type or a filter function which gets passed a node and is expected to return a boolean. For a list of [CommonMark][3] node types see [mdAst][2]. Eventually, the plug-in function returns the tree's root node again. -Note the `options` argument: this is how your plug-in would get passed its config options (see [Installing Plug-Ins][7]). +It uses a *visit* utility function (see [mdast-util-visit 🌎][11]) with a filter argument (2) and visitor callback argument (3). The filter argument can be the name of a node type or a filter function which gets passed a node and is expected to return a boolean. For a list of [CommonMark 🌎][6] node types see [mdAst 🌎][5]. Eventually, the plug-in function returns the tree's root node again. +Note the `options` argument: this is how your plug-in would get passed its [config options][12] (see [Installing Plug-Ins][13]). Let's save the plug-in to *plugins/remark-my-plug-in.js* next to `outDir`: @@ -71,13 +67,13 @@ In your `glossarify-md.conf.json` add: ``` The plug-in path is rooted in `outDir` so you need to step out. -That's it. Run [glossarify-md][5] again and check the links in Markdown files in your output directory. +That's it. Run [glossarify-md][8] again and check the links in Markdown files in your output directory. ## [Creating a Plug-in Package (optional)](#creating-a-plug-in-package-optional) -If you aim for publishing a plug-in, here's how you could set up a plug-in package project next to a [glossarify-md][5] project: +If you aim for publishing a plug-in, here's how you could set up a plug-in package project next to a [glossarify-md][8] project: -1. Make a new directory *remark-my-plug-in* next to `${root}` and initialize it as an [npm][8] package. +1. Make a new directory *remark-my-plug-in* next to `${root}` and initialize it as an [npm 🌎][14] package. mkdir ./remark-my-plug-in cd ./remark-my-plug-in @@ -90,21 +86,21 @@ If you aim for publishing a plug-in, here's how you could set up a plug-in packa 3. Copy the JavaScript code sample or `remark-my-plug-in.js` (see prev. section) to a file `index.js` -4. Install the [npm][8] dependency required by the code sample +4. [Install][15] the [npm 🌎][14] dependency required by the code sample npm install unist-util-visit -5. You're now set with your plug-in. This step will make your package usuable, *locally*, with symlinking (since it's not yet published to [npm][8]). +5. You're now set with your plug-in. This step will make your package usuable, *locally*, with symlinking (since it's not yet published to [npm 🌎][14]). - `cd` into your [glossarify-md][5] project and create another symlink onto the global symlink: + `cd` into your [glossarify-md][8] project and create another symlink onto the global symlink: npm link ../remark-my-plug-in > **Important:** Ths step needs to be repeated whenever you ran `npm install` in your glossarify-md project. - You now virtually "installed" your plug-in to your [glossarify-md][5] project similar as if you had run `npm install remark-my-plug-in` to fetch it from the [npm][8] registry. What's left is configuring glossarify-md to use it (see also previous section): + You now virtually "installed" your plug-in to your [glossarify-md][8] project similar as if you had run `npm install remark-my-plug-in` to fetch it from the [npm 🌎][14] registry. What's left is configuring glossarify-md to use it (see also previous section): -6. Add to your *[glossarify-md][5].conf.json* +6. Add to your *[glossarify-md][8].conf.json* unified: { "plugins": { @@ -112,7 +108,7 @@ If you aim for publishing a plug-in, here's how you could set up a plug-in packa } } -7. Delete your `outDir`, run [glossarify-md][5] again and see whether link output changed. +7. Delete your `outDir`, run [glossarify-md][8] again and see whether link output changed. ### [Publishing a Plug-in Package](#publishing-a-plug-in-package) @@ -122,24 +118,38 @@ Prior to publishing check what would get published: The command creates a `tar.gz` file. Inspect its contents. Optionally, use a `files` whitelist in `package.json` to select which files should go into a package. -> Prior to publishing to the official npm registry, you may also find setting up a test registry on `localhost` useful. See [verdaccio], for an example. +> Prior to publishing to the official npm registry, you may also find setting up a test registry on `localhost` useful. See verdaccio, for an example. + +More see official [NPM 🌎][14] docs on [publishing your node package][16]. + +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins-dev.md#syntax-plug-ins "Syntax Plug-ins extend Markdown syntax itself, like remark-frontmatter, for example." + +[2]: https://npmjs.com/package/remark-frontmatter "A remark syntax plug-in supporting pseudo-standard front-matter syntax." + +[3]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins.md#installing-and-configuring-plug-ins "The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp." + +[4]: https://github.com/micromark/ "A low-level extensible implementation of the CommonMark syntax specification (parsing and tokenizing)." + +[5]: https://github.com/syntax-tree/mdast "Specification and Implementation of a Markdown Abstract Syntax Tree." + +[6]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." -More see official [NPM][8] docs on [publishing your node package][9]. +[7]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" -[1]: https://github.com/micromark/ "A low-level extensible implementation of the CommonMark syntax specification (parsing and tokenizing)." +[8]: https://github.com/about-code/glossarify-md -[2]: https://github.com/syntax-tree/mdast "Specification and Implementation of a Markdown Abstract Syntax Tree." +[9]: https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md#internals-conceptual-layers "Conceptual layers of text processing by glossarify-md and projects contributing to each layer glossarify-md is built on unified, an umbrella project for text file processing in general." -[3]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." +[10]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." -[4]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" +[11]: https://npmjs.com/package/mdast-util-visit -[5]: https://github.com/about-code/glossarify-md "This project." +[12]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md -[6]: ./glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." +[13]: #installing-plug-ins -[7]: #installing-plug-ins +[14]: https://npmjs.com "Node Package Manager." -[8]: https://npmjs.com "Node Package Manager." +[15]: https://github.com/about-code/glossarify-md/blob/master/doc/install.md#install -[9]: https://docs.npmjs.com/packages-and-modules +[16]: https://docs.npmjs.com/packages-and-modules diff --git a/doc/plugins.md b/doc/plugins.md index 64cb2c34..338dc42f 100644 --- a/doc/plugins.md +++ b/doc/plugins.md @@ -1,24 +1,12 @@ # [Installing and Configuring Plug-ins](#installing-and-configuring-plug-ins) -[doc-conceptual-layers]: ./conceptual-layers.md - -[doc-plugins-dev]: ./plugins-dev.md - -[doc-mdext-syntax]: ./markdown-syntax-extensions.md - -[mdast-util-visit]: https://npmjs.com/package/mdast-util-visit - -[remark-discussion]: https://github.com/remarkjs/remark/discussions/869#discussioncomment-1602674 - -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter - -[remark-plugin]: https://github.com/remarkjs/awesome-remark + [unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md -[verdaccio]: https://npmjs.com/package/verdaccio - -The following example demonstrates how to install [remark-frontmatter], a [remark plug-in][remark-plugin] to make [glossarify-md][1] handle non-standard *Frontmatter* syntax, correctly ([When do I need a plug-in?][doc-mdext-syntax]). +The following example demonstrates how to [install][1] [remark-frontmatter 🌎][2], a syntax plug-in from the [remark 🌎][3] [plug-in ecosystem 🌎][4] which makes [glossarify-md][5] (resp. its internal remark parser) handle non-standard *Frontmatter* syntax, correctly (See [Markdown Syntax Extensions][6] for when you need a plug-in). > **ⓘ Note:** glossarify-md does not guarantee compatibility with plug-ins and likely won't help with issues arising due to installing and using additional third-party plug-ins. @@ -32,7 +20,7 @@ We'll assume the following project structure: |- package.json '- .gitignore -**1:** Install [remark-frontmatter]: +**1:** [Install][1] [remark-frontmatter 🌎][2]: npm install remark-frontmatter @@ -53,10 +41,10 @@ We'll assume the following project structure: Keys of the `plugins` object tell what plug-in to load and may be: -* a name of an [npm][2] package in a global or local `node_modules` folder -* a path to a JavaScript file exporting a plug-in function (see [writing plug-ins][doc-plugins-dev]) +* a name of an [npm 🌎][7] package in a global or local `node_modules` folder +* a path to a JavaScript file [exporting][8] a plug-in function (see page [Writing a Plug-in][9]) -Their value in turn are options passed to the plug-in. Read [remark-frontmatter] docs, to find out about available options. +Their value in turn are options passed to the plug-in. Read [remark-frontmatter 🌎][2] docs, to find out about available options. > ⓘ The `unified` key embeds a [unified configuration][unified-config] object. Its schema is *not* subject to glossarify-md's own config schema, anymore. Thus, if you would like to have the configs separated a bit more clearly, then you can split them: > @@ -84,9 +72,27 @@ Their value in turn are options passed to the plug-in. Read [remark-frontmatter] > } > } > ``` -> -> If you would like to learn more about how *unified* and *remark* relate to glossarify-md, read [Conceptual Layers][doc-conceptual-layers]. -[1]: https://github.com/about-code/glossarify-md "This project." +If you would like to learn more about how *[unified 🌎][10]* and *[remark 🌎][3]* relate to [glossarify-md][5], read [Conceptual Layers][11] + +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/install.md#install + +[2]: https://npmjs.com/package/remark-frontmatter "A remark syntax plug-in supporting pseudo-standard front-matter syntax." + +[3]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." + +[4]: https://github.com/remarkjs/awesome-remark "A curated list of remark plug-ins." + +[5]: https://github.com/about-code/glossarify-md + +[6]: https://github.com/about-code/glossarify-md/blob/master/doc/markdown-syntax-extensions.md#markdown-syntax-extensions "glossarify-md supports CommonMark and GitHub Flavoured Markdown (GFM)." + +[7]: https://npmjs.com "Node Package Manager." + +[8]: https://github.com/about-code/glossarify-md/blob/master/doc/export.md#export "Since v6.0.0 Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory." + +[9]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins-dev.md#writing-a-plug-in + +[10]: https://unifiedjs.com "unified is an umbrella project around text file processing in general." -[2]: https://npmjs.com "Node Package Manager." +[11]: https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md#internals-conceptual-layers "Conceptual layers of text processing by glossarify-md and projects contributing to each layer glossarify-md is built on unified, an umbrella project for text file processing in general." diff --git a/doc/references.md b/doc/references.md index f3eadc1f..f0291cb8 100644 --- a/doc/references.md +++ b/doc/references.md @@ -1,46 +1,29 @@ -# [Managing References](#managing-references) +# [Citations and References](#citations-and-references) -In order to cite a source on the web whenever using a particular [term★][1] use a glossary configuration with `linkUris: true`: +[Shannon1948]: https://doi.org/10.1002/j.1538-7305.1948.tb01338.x -*[glossarify-md][2].conf.json* - -```json -{ - "glossaries": [ - { - "file": "./references.md", - "linkUris": true - } - ] -} -``` - -Within file `./references.md` use the [term★][1] attribute `uri` to provide the source's [URL★][3]. Optionally you can add an `aliases` [term attribute★][4] to make further terms refer to a particular source and provide a tooltip for the link. - -*references.md* +A way to use [glossarify-md][1] for citing and linking is to have a file, e.g. `references.md` ... ```md -## CommonMark - - -## Dublin Core - -The Dublin Core Metadata Initiative. -``` - -See an example by inspecting the markdown source of [\_references.md][5] or this repository's [glossarify-md.conf.json][6]. +# References -[1]: ./glossary.md#term "A term is denoted by a heading in a markdown file which is told glossarify-md to be a glossary file." +## Shannon1948 + -[2]: https://github.com/about-code/glossarify-md "This project." +C. E. Shannon, "A mathematical theory of communication," in The Bell System Technical Journal, vol. 27, no. 3, pp. 379-423, July 1948, doi: 10.1002/j.1538-7305.1948.tb01338.x. +``` -[3]: ./glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." +...and configure it as a glossary: -[4]: ./glossary.md#term-attribute "Term Attributes are passed in a comment following a term's heading." +```json +{ + "glossaries": [{ + "file": "./references.md", + "linkUris": true + }] +} +``` -[5]: ./_references.md +Use `linkUris: true` to make [glossarify-md][1] link occurrences of [Shannon1948] to the web using its `uri`. With `linkUris: false` (default) it links to `references.md`. -[6]: ../glossarify-md.conf.json +[1]: https://github.com/about-code/glossarify-md diff --git a/doc/skos-interop.md b/doc/skos-interop.md index e9d04b30..3432b323 100644 --- a/doc/skos-interop.md +++ b/doc/skos-interop.md @@ -1,12 +1,12 @@ # [Interoperability with SKOS and JSON-LD](#interoperability-with-skos-and-json-ld) -[doc-export-import]: ../README.md#structured-export-and-import + > Readers Level: *Advanced* > > The term *term* can become itself confusing in this section. Therefore we'll say *model terms* if we refer to a vocabulary of technical attribute names or type names of a data model. We'll say *glossary terms* if we refer to the actual terms of a glossary (an instance of that data model). -**Since v6.0.0** [glossarify-md][1] supports [exporting and importing][doc-export-import] glossaries. In addition to importing terms from files exported by glossarify-md itself it can import glossary terms from arbitrarily structured JSON documents once there are mappings of the other document's *model terms* onto "well-known" [SKOS][2] and [Dublin Core][3] model terms. +**Since v6.0.0** [glossarify-md][1] supports [exporting][2] and [importing][3] glossaries. In addition to importing terms from files exported by glossarify-md itself it can import glossary terms from arbitrarily structured JSON documents once there are mappings of the other document's *model terms* onto "well-known" [SKOS 🌎][4] and [Dublin Core 🌎][5] model terms. Model terms understood by [glossarify-md][1] are: @@ -35,7 +35,7 @@ To see how this works a good starting point is to have a look at a [glossarify-m } ``` -The configuration will make [glossarify-md][1] produce a file +The [configuration][6] will make [glossarify-md][1] produce a file *glossary.json* @@ -77,11 +77,11 @@ The configuration will make [glossarify-md][1] produce a file } ``` -`glossary.json` will embed a [JSON-LD][4] `@context` document. It maps [glossarify-md][1]'s own export model terminology onto [SKOS][2] and [Dublin Core][3] terms for interoperability with *other* tools understanding SKOS and Dublin Core.[^1] +`glossary.json` will embed a [JSON-LD 🌎][7] `@context` document. It maps [glossarify-md][1]'s own [export][2] model terminology onto [SKOS 🌎][4] and [Dublin Core 🌎][5] terms for interoperability with *other* tools understanding SKOS and Dublin Core.[^1] -[^1]: You can map [glossarify-md][1]'s terms onto other model [vocabularies★][5] by adding a `context` attribute to the `export` config. The attribute value is expected to be a path to a `.json` or `.jsonld` file which exposes a document with a `@context` key. +[^1]: You can map [glossarify-md][1]'s terms onto other model [vocabularies][8] by adding a `context` attribute to the `export` config. The attribute value is expected to be a path to a `.json` or `.jsonld` file which exposes a document with a `@context` key. -Next we'll simulate a roundtrip by importing our exported file again. +Next we'll simulate a roundtrip by [importing][3] our exported file again. ### [Importing SKOS Data](#importing-skos-data) @@ -100,7 +100,7 @@ Copy `glossary.json` which you've just exported into your input folder (*baseDir } ``` -Of course, [glossarify-md][1] will be able to import *its own* export format again. But what if you have terms exported by another tool in another format? +Of course, [glossarify-md][1] will be able to [import][3] *its own* [export][2] format again. But what if you have terms exported by another tool in another format? > In case you just ran glossarify-md and there is an `imported.md` file in your `outDir` then delete it. @@ -125,11 +125,11 @@ Let's drop `@context` from `glossary.json` and change it to a very different sch } ``` -This is now a sample format *unknown* to [glossarify-md][1]. Different data formats and semantics like these are a barrier to *interoperability*. That's where [JSON-LD][4] and standardized [vocabularies★][5] enter the game. +This is now a sample format *unknown* to [glossarify-md][1]. Different data formats and semantics like these are a barrier to *interoperability*. That's where [JSON-LD 🌎][7] and standardized [vocabularies][8] enter the game. -If the *unknown* application had embedded [JSON-LD][4] mappings onto [SKOS][2] and [DublinCore][3] the data could have been understood right away. Since few tools do this as of today, we'll be writing these mappings on our own: +If the *unknown* application had embedded [JSON-LD 🌎][7] mappings onto [SKOS 🌎][4] and [DublinCore 🌎][5] the data could have been understood right away. Since few tools do this as of today, we'll be writing these mappings on our own: -*unknown-format.[jsonld][6]* +*unknown-format.[jsonld 🌎][9]* ```json { @@ -165,15 +165,15 @@ Now provide this *external context* document along the imported file: } ``` -What's left is to enhance [glossarify-md][1] with [JSON-LD][4] capabilities for interoperability: [^2] +What's left is to enhance [glossarify-md][1] with [JSON-LD 🌎][7] capabilities for interoperability: [^2] npm install jsonld -[^2]: We could have installed [jsonld][6] together with [glossarify-md][1] by default but decided against to minimize bloat for the average user. +[^2]: We could have installed [jsonld 🌎][9] together with [glossarify-md][1] by default but decided against to minimize bloat for the average user. On the next run [glossarify-md][1] will be looking for `@context` mappings -1. *embedded into the JSON import file* +1. *embedded into the JSON [import][3] file* 2. or provided *externally* using `context` in the `import` config. In our example the second applies. Glossary terms in `term-data.json` from the previously *unknown* format should now have been imported and written to a new markdown file `imported.md`. @@ -182,18 +182,24 @@ To sum up: we've just seen an example of interoperability and how two or more ap ### [Additional Notes](#additional-notes) -* [glossarify-md][1] will only import typed documents directly using [JSON-LD][4]'s `@type` attribute or mapping their `type`-like attribute onto `@type`. Unknown type names need to be mapped onto `skos:ConceptScheme` (the glossary) and `skos:Concept` (the terms). +* [glossarify-md][1] will only [import][3] typed documents directly using [JSON-LD 🌎][7]'s `@type` attribute or mapping their `type`-like attribute onto `@type`. Unknown type names need to be mapped onto `skos:ConceptScheme` (the glossary) and `skos:Concept` (the terms). -* More complicated data formats may require use of some additional [JSON-LD][4] keywords from the JSON-LD Spec. +* More complicated data formats may require use of some additional [JSON-LD 🌎][7] keywords from the JSON-LD Spec. -[1]: https://github.com/about-code/glossarify-md "This project." +[1]: https://github.com/about-code/glossarify-md -[2]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets." +[2]: https://github.com/about-code/glossarify-md/blob/master/doc/export.md#export "Since v6.0.0 Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory." -[3]: http://purl.org/dc/terms/ "The Dublin Core Metadata Initiative." +[3]: https://github.com/about-code/glossarify-md/blob/master/doc/import.md#importing-terms "⚠ Important: glossarify-md is able to import terms and definitions from a remote location using https." -[4]: https://json-ld.org "JSON-LD is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public vocabularies." +[4]: http://w3.org/skos/ "With the Simple Knowledge Organization System (SKOS) the World Wide Web Consortium (W3C) has standardized a (meta-)vocabulary which is suited and intended for modeling Simple Knowledge Organization Systems such as Glossaries, Thesauri, Taxonomies or Word Nets." -[5]: ./glossary.md#vocabulary "A collection of terms which is uniquely identifiable." +[5]: http://purl.org/dc/terms/ "The Dublin Core Metadata Initiative." -[6]: https://npmjs.com/package/jsonld "A JavaScript implementation of JSON-LD." +[6]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md + +[7]: https://json-ld.org "JSON-LD is a standardized JSON document format for mapping system-specific terms of a JSON-based data format to well-know terms from public vocabularies." + +[8]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#vocabulary "A collection of terms which is uniquely identifiable." + +[9]: https://npmjs.com/package/jsonld "A JavaScript implementation of JSON-LD." diff --git a/doc/term-attributes.md b/doc/term-attributes.md index 468787bf..9e42e158 100644 --- a/doc/term-attributes.md +++ b/doc/term-attributes.md @@ -1,48 +1,42 @@ # [Term Attributes](#term-attributes) -[doc-aliases]: ../README.md#aliases-and-synonyms - -[doc-vocabularies]: ./vocabulary-uris.md - -[Term★][1] Attributes are passed in a comment following a term's heading. The comment text must adhere to YAML syntax. - -**Since v6.3.0** [glossarify-md][2] supports YAML syntax. Its easy to learn and a natural fit with Markdown. For example, this will be all you need to understand and use [term★][1] attributes: - -*my-glossary.md* +[Term][1] Attributes provide additional metadata for a term. They are passed in a comment following a term heading: ```md # Term Heading - -... + +Term definition here. ``` -> **ⓘ Note:** YAML syntax is *case-sensitive* and like Markdown it is *sensitive to tabs and whitespaces*. In general term attributes will be lowercase. +**Since v6.3.0** [term][1] attributes use YAML syntax. The example shows two [term attributes][2] `key1` and `key2` where `key2` has multiple attribute values. -## [Attributes](#attributes) +> **ⓘ Note:** YAML syntax is *case-sensitive* and *sensitive to tabs and whitespaces* (like Markdown). As a rule of thumb: our own term attributes will be all lowercase. + +## [Supported Term Attributes](#supported-term-attributes) ### [`aliases`](#aliases) -Comma-separated string or a string array listing alternative spellings that should be linked with a [term★][1] definition when found in text. More see [README.md][doc-aliases] +Expects a comma-separated string or a list of strings which provide synonyms or alternative spellings for a [term][1] that should be linked with a term definition when found in text. More see [README.md][3] -> **ⓘ Note:** You may find that an uppercase `Aliases: ` term attribute works as well. This is going to be the only attribute for which an uppercase name remains supported *for backwards compatibility*. +> **ⓘ Note:** Uppercase `Aliases` remains to be supported for backwards compatibility. ### [`uri`](#uri) -An identifier for the [term★][1]'s *meaning*. Can be used to link term occurrences to an authoritative definition on the web instead of linking term occurrences to a markdown book's glossary. Web linking requires setting `linkUris: true` for a `glossaries` item in a [glossarify-md][2] configuration file. More see *[URIs as Identifiers for Definitions of Meaning][doc-vocabularies]* +A unique identifier for the [term][1] and the definition of it's *meaning*. Use `linkUris: true` with a `glossaries` config in a [glossarify-md][4] [configuration][5] file to link term occurrences to an authoritative definition on the web using the term's `uri` [term attribute][2]. See also *[URIs as Identifiers for Definitions of Meaning][6]*. # [Addendum](#addendum) -There's going to be continued support for JSON [term★][1] attribute syntax, for backwards compatibility. However, it requires some strictness about quotation marks, commas and braces/brackets which makes it easier to run into syntax errors: +There's going to be continued support for JSON [term][1] attribute syntax, for backwards compatibility. However, it requires some strictness about quotation marks, commas and braces/brackets which makes it easier to run into syntax errors: ```md # Term Heading - ``` -If you've been using JSON [term★][1] attribute syntax and want to switch to YAML syntax you might find these regular expressions helpful to use with your editor's Search/Replace assistant: +If you've been using JSON [term][1] attribute syntax and want to switch to YAML syntax you might find these regular expressions helpful to use with your editor's Search/Replace assistant: ### [Example (Single term attribute)](#example-single-term-attribute) @@ -81,7 +75,7 @@ If you've been using JSON [term★][1] attribute syntax and want to switch to YA ```md # Term - @@ -105,12 +99,20 @@ If you've been using JSON [term★][1] attribute syntax and want to switch to YA ```md # Term - ``` -[1]: ./glossary.md#term "A term is denoted by a heading in a markdown file which is told glossarify-md to be a glossary file." +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#term "Terms are headings in a markdown file which has been configured to be a glossary file." + +[2]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#term-attribute "Term Attributes are passed in a comment following a term's heading." + +[3]: https://github.com/about-code/glossarify-md/blob/master/README.md + +[4]: https://github.com/about-code/glossarify-md + +[5]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md -[2]: https://github.com/about-code/glossarify-md "This project." +[6]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md#uris-as-identifiers-for-definitions-of-meaning "Consider a term skin." diff --git a/doc/use-with-hugo.md b/doc/use-with-hugo.md index 6113cd07..c51169ed 100644 --- a/doc/use-with-hugo.md +++ b/doc/use-with-hugo.md @@ -1,10 +1,6 @@ # [Using glossarify-md with Hugo](#using-glossarify-md-with-hugo) -[doc-linking]: https://github.com/about-code/glossarify-md/blob/master/doc/README.md#linking - -[doc-plugins]: ./plugins.md - -[doc-mdext-syntax]: ./markdown-syntax-extensions.md + [hugo-page-bundles]: https://gohugo.io/content-management/page-bundles/ @@ -14,29 +10,27 @@ [hugo-cm-compliance]: https://github.com/about-code/glossarify-md/issues/165#issuecomment-1086874898 -[known issues]: #known-issues - -Below we provide a few *examples* on how you *might* be able to facilitate [glossarify-md][1] in a [Hugo][2] project. But note that existence of this page is not a statement about *Hugo compatibility*. +Below we provide a few *examples* on how you *might* be able to facilitate [glossarify-md][1] in a [Hugo 🌎][2] project. But note that existence of this page is not a statement about *Hugo compatibility*. -## [Setup](#setup) +## [Setup Hugo with glossarify-md](#setup-hugo-with-glossarify-md) -1. Install [NodeJS][3] and [npm][4] -2. In your [Hugo][2] project folder install [glossarify-md][1] +1. [Install][3] [NodeJS 🌎][4] and [npm 🌎][5] +2. In your [Hugo 🌎][2] project folder [install][3] [glossarify-md][1] npm install glossarify-md npx glossarify-md --init --local > glossarify-md.conf.json echo node_modules >> .gitignore -3. In your [Hugo][2] project folder rename `content` to `content_`. +3. In your [Hugo 🌎][2] project folder rename `content` to `content_`. ## [Install Plug-Ins](#install-plug-ins) -[Hugo][2] supports some Markdown syntax not [supported out-of-the-box by glossarify-md][doc-mdext-syntax]. See the table below which syntax (left column) requires [installing and configuring a plug-in][doc-plugins] (right column). See the plug-in's docs for available config options and default values. +[Hugo 🌎][2] supports some [Markdown syntax extensions][6] not supported out-of-the-box by [glossarify-md][1]. See the table below which kind of syntax (left column) requires [installing and configuring a plug-in][7] (right column). See the plug-in's docs for available [config options][8] and default values. npm install remark-frontmatter remark-shortcodes | Markdown Syntax Extension | plug-in required with [glossarify-md][1] | | ------------------------------- | ---------------------------------------- | -| [Frontmatter][hugo-frontmatter] | [remark-frontmatter][5] | -| [Shortcodes][hugo-shortcodes] | [remark-shortcodes][6] | +| [Frontmatter][hugo-frontmatter] | [remark-frontmatter 🌎][9] | +| [Shortcodes][hugo-shortcodes] | [remark-shortcodes 🌎][10] | | ...and maybe others | | ## [Configure glossarify-md](#configure-glossarify-md) @@ -62,11 +56,11 @@ Below we provide a few *examples* on how you *might* be able to facilitate [glos ### [Option 1: Configure for a Hugo "Leaf Bundle Structure"](#option-1-configure-for-a-hugo-leaf-bundle-structure) -In a [Hugo][2] [Leaf Bundle Structure][hugo-page-bundles] +In a [Hugo 🌎][2] [Leaf Bundle Structure][hugo-page-bundles] * each directory represents a page * the main content is in an `index.md` Markdown file -* only the directory name will be part of the page's [URL★][7] path segments. +* only the directory name will be part of the page's [URL][11] path segments. Its easier to configure [glossarify-md][1] for a Leaf Bundle Structure: @@ -117,11 +111,11 @@ ${root} ### [Option 2: Configure for a Hugo "Branch Bundle Structure"](#option-2-configure-for-a-hugo-branch-bundle-structure) -In a [Hugo][2] [Branch Bundle Structure][hugo-page-bundles] +In a [Hugo 🌎][2] [Branch Bundle Structure][hugo-page-bundles] * Markdown files in the directory represent individual pages * each directory has an `_index.md` Markdown file -* directory *and* file names (without file extension) become [URL★][7] path segments. +* directory *and* file names (without file extension) become [URL][11] path segments. @@ -169,57 +163,69 @@ In a [Hugo][2] [Branch Bundle Structure][hugo-page-bundles] } ``` -## [Run](#run) +## [Run glossarify-md](#run-glossarify-md) npx glossarify-md --config ./glossarify-md.conf.json -You should now see the files in `content_` copied to `content` where they will be picked up by [Hugo][2]. Should you have any troubles with paths, see also [`linking` options][doc-linking]. +You should now see the files in `content_` copied to `content` where they will be picked up by [Hugo 🌎][2]. Should you have any troubles with paths, see also `linking` [config option][8]. ## [Known Issues](#known-issues) ### [Different Flavours of "Markdown"](#different-flavours-of-markdown) -[https://github.com/about-code/glossarify-md/issues/246][8] +[https://github.com/about-code/glossarify-md/issues/246][12] -[Hugo][2] and [glossarify-md][1] support an overlapping, yet not identical set of Markdown syntax constructs. They share the common set of [CommonMark][9] and [GFM][10] constructs. But there is a chance Hugo supports additional features neither in Commonmark nor GFM. As a glossarify-md-with-Hugo user you may +[Hugo 🌎][2] and [glossarify-md][1] support an overlapping, yet not identical set of Markdown syntax constructs. They share the common set of [CommonMark 🌎][13] and [GFM 🌎][14] constructs. But there is a chance Hugo supports additional features neither in Commonmark nor GFM. As a glossarify-md-with-Hugo user you may * need to restrict yourself to using the common set of syntax, only -* or need to [install a syntax plug-in][doc-plugins], when there's one available -* or need to step back from [glossarify-md][1] given you can't sacrifice certain [Hugo][2] features. +* or need to [install][3] a syntax plug-in, when there's one available +* or need to step back from [glossarify-md][1] given you can't sacrifice certain [Hugo 🌎][2] features. ### [Shortcodes in Markdown Links](#shortcodes-in-markdown-links) [https://github.com/about-code/glossarify-md/issues/165#issuecomment-1086874898][hugo-cm-compliance] -[glossarify-md][1] can be enhanced with syntax plug-ins to accept shortcode syntax. But it won't be able to support certain combinations of [CommonMark][9] syntax *and* shortcode syntax, e.g. CommonMark link syntax `[]()` combined with shortcode syntax `{{< relref >}}` to something like `[Foo]({{< relref bar >}})`. glossarify-md requires valid CommonMark input but the combined syntax [is not valid CommonMark][hugo-cm-compliance] (as of CommonMark v0.30). +[glossarify-md][1] can be enhanced with [syntax plug-ins][15] to accept shortcode syntax. But it won't be able to support certain combinations of [CommonMark 🌎][13] syntax *and* shortcode syntax, e.g. CommonMark link syntax `[]()` combined with shortcode syntax `{{< relref >}}` to something like `[Foo]({{< relref bar >}})`. glossarify-md requires valid CommonMark input but the combined syntax [is not valid CommonMark][hugo-cm-compliance] (as of CommonMark v0.30). ### [Things get escaped with `\`](#things-get-escaped-with-) There may be two reasons: 1. input files use custom syntax not understood by [glossarify-md][1]. See known issue *Different flavors of Markdown*, above. -2. there is an improper combination of [CommonMark][9] syntax elements and non-standard syntax which violates the CommonMark spec. For an example, see known issue *Shortcodes in Markdown Links*, above. +2. there is an improper combination of [CommonMark 🌎][13] syntax elements and non-standard syntax which violates the CommonMark spec. For an example, see known issue *[Shortcodes in Markdown Links][16]*, above. ### [Link paths](#link-paths) -[Hugo][2] has its own means of producing website URLs from a project's filesystem. We have shown [glossarify-md][1] configurations that fit a particular project structure but they have not been tested beyond a few simple Hugo demo pages. Feel free to experiment with glossarify-md options and [`linking` options][doc-linking] in particular if the config doesn't work for you. +[Hugo 🌎][2] has its own means of producing website URLs from a project's filesystem. We have shown [glossarify-md][1] configurations that fit a particular project structure but they have not been tested beyond a few simple Hugo demo pages. Feel free to experiment with glossarify-md options and \[`linking` options]\[doc-linking] in particular if the config doesn't work for you. -[1]: https://github.com/about-code/glossarify-md "This project." +[1]: https://github.com/about-code/glossarify-md [2]: https://gohugo.io "A static website renderer compiling an HTML website from Markdown files." -[3]: https://nodejs.org +[3]: https://github.com/about-code/glossarify-md/blob/master/doc/install.md#install + +[4]: https://nodejs.org + +[5]: https://npmjs.com "Node Package Manager." + +[6]: https://github.com/about-code/glossarify-md/blob/master/doc/markdown-syntax-extensions.md#markdown-syntax-extensions "glossarify-md supports CommonMark and GitHub Flavoured Markdown (GFM)." + +[7]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins.md#installing-and-configuring-plug-ins "The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp." + +[8]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md + +[9]: https://npmjs.com/package/remark-frontmatter "A remark syntax plug-in supporting pseudo-standard front-matter syntax." -[4]: https://npmjs.com "Node Package Manager." +[10]: https://www.npmjs.com/package/remark-shortcodes "A remark syntax plug-in supporting non-standard Hugo shortcodes syntax." -[5]: https://npmjs.com/package/remark-frontmatter "A remark syntax plug-in supporting pseudo-standard front-matter syntax." +[11]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." -[6]: https://www.npmjs.com/package/remark-shortcodes "A remark syntax plug-in supporting non-standard Hugo shortcodes syntax." +[12]: https://github.com/about-code/glossarify-md/issues/246 -[7]: ./glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." +[13]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." -[8]: https://github.com/about-code/glossarify-md/issues/246 +[14]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" -[9]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." +[15]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins-dev.md#syntax-plug-ins "Syntax Plug-ins extend Markdown syntax itself, like remark-frontmatter, for example." -[10]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" +[16]: https://github.com/about-code/glossarify-md/blob/master/doc/use-with-hugo.md#shortcodes-in-markdown-links "https://github.com/about-code/glossarify-md/issues/165#issuecomment-1086874898 glossarify-md can be enhanced with syntax plug-ins to accept shortcode syntax." diff --git a/doc/use-with-pandoc.md b/doc/use-with-pandoc.md index f395c5c6..0424d575 100644 --- a/doc/use-with-pandoc.md +++ b/doc/use-with-pandoc.md @@ -1,5 +1,7 @@ # [Using glossarify-md with pandoc](#using-glossarify-md-with-pandoc) + + ${root} +- docs/ +- docs-glossarified/ (Generated) @@ -32,13 +34,13 @@ } ``` -When [pandoc][2] merges multiple files into a single file we need to take care for +When [pandoc 🌎][2] merges multiple files into a single file we need to take care for link stability and paths. 1. `linking.paths: "none"` disables the use of paths and uses heading ids (anchors), only 2. `headingIdPandoc: true` adds pandoc-style `{# foo}` attributes taken by - [pandoc][2] for its own linking + [pandoc 🌎][2] for its own linking 3. `headingIdAlgorithm: "md5"` generates a heading ID based on a hashsum which is unique accross the file set and therefore within a pandoc-merged file, too. Other values may be `md5-7, sha256, sha256-7`. @@ -55,6 +57,6 @@ After having set these options, files can be merged, e.g. with pandoc --from=markdown -o out.html ./docs-glossarified/**/*.md -[1]: https://github.com/about-code/glossarify-md "This project." +[1]: https://github.com/about-code/glossarify-md [2]: https://pandoc.org "See pandoc." diff --git a/doc/use-with-vuepress.md b/doc/use-with-vuepress.md index 95f906cd..682c0777 100644 --- a/doc/use-with-vuepress.md +++ b/doc/use-with-vuepress.md @@ -1,10 +1,20 @@ # [Using glossarify-md with vuepress](#using-glossarify-md-with-vuepress) -Below we assume a *sample* project structure like this: + + +[vp-frontmatter]: https://vuepress.vuejs.org/guide/markdown.html#frontmatter + +[vp-cc]: https://vuepress.vuejs.org/guide/markdown.html#custom-containers + +[vp-emoji]: https://vuepress.vuejs.org/guide/markdown.html#emoji -[doc-syntax-extensions]: ./markdown-syntax-extensions.md +[vp-toc]: https://vuepress.vuejs.org/guide/markdown.html#table-of-contents + +[vp-lh]: https://vuepress.vuejs.org/guide/markdown.html#line-highlighting-in-code-blocks -[doc-plugins]: ./plugins.md +[vp-code]: https://vuepress.vuejs.org/guide/markdown.html#import-code-snippets + +Below we assume a *sample* project structure like this: ${root} +- docs/ @@ -50,7 +60,7 @@ Below we assume a *sample* project structure like this: ## [Configure vuepress](#configure-vuepress) -[glossarify-md][1] and [vuepress][2] need to be aligned in terms of how they create URL-friendly IDs for section anchors also called "[slugs★][3]" (see \[*why?*]\[Appendix])(#appendix). +[glossarify-md][1] and [vuepress 🌎][2] need to be aligned in terms of how they create URL-friendly IDs for section anchors also called "[slugs][3]" (see \[*why?*]\[Appendix])(#[appendix][4]). ./docs/.vuepress/config.js @@ -91,42 +101,30 @@ module.exports = { * `npm start` builds and serves files quickly from `baseDir` with *live-reload*. This is what you probably want while writing even though it doesn't produce glossarified output. * `npm run glossarify` writes glossarified markdown files to `outDir` * `npm run glossarified` builds and serves the glossarified version from `outDir`. -* `npm run build` just builds the glossarified [vuepress][2] site without running a server. +* `npm run build` just builds the glossarified [vuepress 🌎][2] site without running a server. -More information see [README.md][4]. +More information see [README.md][5]. ## [Install and Configure Syntax Extension Plug-Ins](#install-and-configure-syntax-extension-plug-ins) -[vuepress][2] supports some [Markdown syntax][5] not covered by [CommonMark][6] or [GFM][7]. See the table below which syntax extension on the left requires [installing and configuring a plug-in][doc-plugins] on the right. See the respective plug-in for its individual default values and config options. - -| Markdown Syntax Extension | [remark][8] plug-in required with [glossarify-md][1] | -| ------------------------------------- | ---------------------------------------------------- | -| [Frontmatter][vp-frontmatter] | [remark-frontmatter][9] | -| [Custom Containers][vp-cc] | - | -| [Table of Contents][vp-toc] `[[toc]]` | - | -| [Emoji][vp-emoji] | - | -| [Line Highlighting Codeblocks][vp-lh] | - | -| [Import Code Snippets][vp-code] | - | +[vuepress 🌎][2] supports some [Markdown syntax][6] not covered by [CommonMark 🌎][7] or [GFM 🌎][8]. See the table below which syntax extension on the left requires [installing and configuring a plug-in][9] on the right. See the respective plug-in for its individual default values and [config options][10]. -[vp-frontmatter]: https://vuepress.vuejs.org/guide/markdown.html#frontmatter - -[vp-cc]: https://vuepress.vuejs.org/guide/markdown.html#custom-containers - -[vp-emoji]: https://vuepress.vuejs.org/guide/markdown.html#emoji - -[vp-toc]: https://vuepress.vuejs.org/guide/markdown.html#table-of-contents - -[vp-lh]: https://vuepress.vuejs.org/guide/markdown.html#line-highlighting-in-code-blocks - -[vp-code]: https://vuepress.vuejs.org/guide/markdown.html#import-code-snippets +| Markdown Syntax Extension | [remark 🌎][11] plug-in required with [glossarify-md][1] | +| ------------------------------------- | -------------------------------------------------------- | +| [Frontmatter][vp-frontmatter] | [remark-frontmatter][12] | +| [Custom Containers][vp-cc] | - | +| [Table of Contents][vp-toc] `[[toc]]` | - | +| [Emoji][vp-emoji] | - | +| [Line Highlighting Codeblocks][vp-lh] | - | +| [Import Code Snippets][vp-code] | - | ## [Appendix](#appendix) -*[Slugs★][3]* are "*URL-friendly IDs*" used to identify a content section *within* a hypermedia document. They are not required to locate the document but needed to make a browser navigate to a particular content section *within* a document, for example `https://foo.com/#my-slug` identifies a content section using the Slug or *[URL fragment★][10]* `#my-slug`. +*[Slugs][3]* are "*URL-friendly IDs*" used to identify a content section *within* a hypermedia document. They are not required to locate the document but needed to make a browser navigate to a particular content section *within* a document, for example `https://foo.com/#my-slug` identifies a content section using the Slug or *[URL fragment][13]* `#my-slug`. -"*URL-friendly*" means *only certain characters, allowed*. In particular, *whitespaces* need to be encoded. During *[linkification★][11]* [vuepress][2] and glossarify derive [slugs★][3] from section headings but use different algorithms. They may differ in how they replace whitespaces in the IDs derived from a heading text. As a consequence there's a risk of ending up with broken book-internal links (see [#27][12]). To avoid this vuepress needs to be configured to use the same slugger as [glossarify-md][1]. In case you want to get rid of glossarify-md you most likely do *not* want to have slugs change, again. You can use \[github-slugger] standalone without glossarify-md, like so: +"*URL-friendly*" means *only certain characters, allowed*. In particular, *whitespaces* need to be encoded. During *[linkification][14]* [vuepress 🌎][2] and glossarify derive [slugs][3] from section headings but use different algorithms. They may differ in how they replace whitespaces in the IDs derived from a heading text. As a consequence there's a risk of ending up with broken book-internal links (see [#27][15]). To avoid this vuepress needs to be configured to use the same slugger as [glossarify-md][1]. In case you want to get rid of glossarify-md you most likely do *not* want to have slugs change, again. You can use \[github-slugger] standalone without glossarify-md, like so: -*Using [github-slugger][13] without [glossarify-md][1]* +*Using [github-slugger 🌎][16] without [glossarify-md][1]* ```js const GitHubSlugger = require("github-slugger"); @@ -142,30 +140,36 @@ module.exports = { }; ``` -[1]: https://github.com/about-code/glossarify-md "This project." +[1]: https://github.com/about-code/glossarify-md [2]: https://vuepress.vuejs.org "A static website generator translating markdown files into a website powered by [vuejs]." -[3]: ./glossary.md#slug "A slug is a URL-friendly identifier that can be used within URL fragments to address headings / sections on a page." +[3]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#slug "A slug is a URL-friendly identifier that can be used within URL fragments to address headings / sections on a page." + +[4]: https://github.com/about-code/glossarify-md/blob/master/doc/use-with-vuepress.md#appendix "Slugs are \"URL-friendly IDs\" used to identify a content section within a hypermedia document." + +[5]: ../README.md + +[6]: https://vuepress.vuejs.org/guide/markdown.html -[4]: ../README.md +[7]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." -[5]: https://vuepress.vuejs.org/guide/markdown.html +[8]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" -[6]: https://commonmark.org "Effort on providing a minimal set of standardized Markdown syntax." +[9]: https://github.com/about-code/glossarify-md/blob/master/doc/plugins.md#installing-and-configuring-plug-ins "The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp." -[7]: https://github.github.com/gfm/ "GitHub Flavoured Markdown" +[10]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md -[8]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." +[11]: https://github.com/remarkjs/remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." -[9]: http://unifiedjs.com/explore/package/remark-frontmatter/ +[12]: http://unifiedjs.com/explore/package/remark-frontmatter/ -[10]: ./glossary.md#url-fragment "The fragment is the part follwing the # in a URL." +[13]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#url-fragment "The fragment is the part follwing the # in a URL." -[11]: ./glossary.md#linkification "Process of searching for a term in document A matching a heading phrase in +[14]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#linkification "Process of searching for a term in document A matching a heading phrase in document B and replacing the term in document A with a Markdown link pointing onto the term definition in document B." -[12]: https://github.com/about-code/glossarify-md/issues/27 +[15]: https://github.com/about-code/glossarify-md/issues/27 -[13]: https://npmjs.com/package/github-slugger "A library providing support for slugs." +[16]: https://npmjs.com/package/github-slugger "A library providing support for slugs." diff --git a/doc/vocabulary-uris.md b/doc/vocabulary-uris.md index b34aa11a..bbe2c229 100644 --- a/doc/vocabulary-uris.md +++ b/doc/vocabulary-uris.md @@ -1,14 +1,18 @@ # [URIs as Identifiers for *Definitions of Meaning*](#uris-as-identifiers-for-definitions-of-meaning) + + [headingIdAlgorithm]: ../README.md#headingidalgorithm [doc-import]: ../README.md#structured-export-and-import [doc-skos]: ./skos-interop.md -Consider a [term★][1] *skin*. In human medicine it's a term for a human organ while in computer science its often used to refer to a software's look and feel. These kinds of *ambiguities* demand *clarification* which is what glossaries are meant for, of course. +Consider a [term][1] *skin*. In human medicine it's a term for a human organ while in computer science its often used to refer to a software's look and feel. These kinds of *ambiguities* demand *clarification* which is what glossaries are meant for, of course. -*A computer program* can't understand a natural language description of a [term★][1]'s meaning. What it is good at is comparing and distingushing *symbols*. With unique IDs like +*A computer program* can't understand a natural language description of a [term][1]'s meaning. What it is good at is comparing and distingushing *symbols*. With unique IDs like * `https://example.com/glossary/medicine/#skin` * `https://example.com/glossary/computer-science/#skin`. @@ -19,7 +23,7 @@ a computer can operate on symbols equivalent to *some meaning* without having to ## [Vocabulary URIs and Term URIs](#vocabulary-uris-and-term-uris) -`glossaries` entries can be augmented with a `uri` config option which assigns a glossary a so-called *[vocabulary★][3] [URI★][4]*. Then on exporting *[term★][1] URIs* can be derived from the vocabulary URI and a term's *heading ID* by appending the heading ID to the vocabulary URI (see [headingIdAlgorithm] for how [glossarify-md][2] generates heading IDs). +`glossaries` entries can be augmented with a `uri` [config option][3] which assigns a glossary a so-called *[vocabulary][4] [URI][5]*. Then on [exporting][6] *[term][1] URIs* can be derived from the vocabulary [URI][7] and a term's *heading ID* by appending the heading ID to the vocabulary URI (see [headingIdAlgorithm] for how [glossarify-md][2] generates heading IDs). ```json { @@ -33,10 +37,10 @@ a computer can operate on symbols equivalent to *some meaning* without having to } ``` -If you need more control about a [term★][1]'s Term [URI★][4], then there are two switches you can tweak: +If you need more control about a [term][1]'s Term [URI][5], then there are two switches you can tweak: * providing a custom heading ID using pandoc-style `{#headingId}` -* providing a `uri` [term★][1] attribute +* providing a `uri` [term][1] attribute *Custom heading ID* @@ -48,7 +52,7 @@ If you need more control about a [term★][1]'s Term [URI★][4], then there are Term with an individual URI. ``` -*`uri` [term★][1] attribute*: +*`uri` [term][1] attribute*: ```md # Glossary @@ -63,13 +67,13 @@ Term with an individual URI. ### [Resolvability](#resolvability) -URIs can be *just identifiers*. But URIs can also be used to *locate and retrieve* representations of what they identify over a network protocol like HTTPS. For example, a web browser and a [term★][1]'s [URI★][4] could be used to retrieve an HTML representation with a human readable definition of a term. A `glossaries` entry with `linkUris: true` will make [glossarify-md][2] link term occurrences with a *book-external* authoritative definition on the web rather than with the book-internal glossary. On [imported][doc-import] glossaries `showUris: true` or `showUris: "${uri}"` will render URI links in the markdown glossary generated from imported terms. +URIs can be *just identifiers*. But URIs can also be used to *locate and retrieve* representations of what they identify over a network protocol like HTTPS. For example, a web browser and a [term][1]'s [URI][5] could be used to retrieve an HTML representation with a human readable definition of a term. A `glossaries` entry with `linkUris: true` will make [glossarify-md][2] link term occurrences with a *book-external* authoritative definition on the web rather than with the book-internal glossary. On [imported][doc-import] glossaries `showUris: true` or `showUris: "${uri}"` will render [URI][7] links in the markdown glossary generated from imported terms. ### [Authority](#authority) -URIs for terms reveal the authoritative source for a particular definition, which in our example was `example.com`. While anyone could use any domain name in an [URI★][4] and make it the identifier of something (like we did in our examples) only the legitimate domain name owner as registered in the Domain Name System (DNS) can claim authority in case of disputes over some definition. +URIs for terms reveal the authoritative source for a particular definition, which in our example was `example.com`. While anyone could use any domain name in an [URI][5] and make it the identifier of something (like we did in our examples) only the legitimate domain name owner as registered in the Domain Name System (DNS) can claim [authority][8] in case of disputes over some definition. -So in this particular example we could *not* veto if the owners of domain `example.com` chose to use above URIs to identify something else. By using another domain name than our own we effectively accept that there could be conflicting definitions wiping out the purpose of an [URI★][4]. So particularly when publishing a [vocabulary★][3] it is usually not a good idea to use someone else's domain. +So in this particular example we could *not* veto if the owners of domain `example.com` chose to use above URIs to identify something else. By using another domain name than our own we effectively accept that there could be conflicting definitions wiping out the purpose of an [URI][5]. So particularly when publishing a [vocabulary][4] it is usually not a good idea to use someone else's domain. -[1]: ./glossary.md#term "A term is denoted by a heading in a markdown file which is told glossarify-md to be a glossary file." +[1]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#term "Terms are headings in a markdown file which has been configured to be a glossary file." + +[2]: https://github.com/about-code/glossarify-md + +[3]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md + +[4]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#vocabulary "A collection of terms which is uniquely identifiable." + +[5]: https://github.com/about-code/glossarify-md/blob/master/doc/glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." -[2]: https://github.com/about-code/glossarify-md "This project." +[6]: https://github.com/about-code/glossarify-md/blob/master/doc/export.md#export "Since v6.0.0 Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory." -[3]: ./glossary.md#vocabulary "A collection of terms which is uniquely identifiable." +[7]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md#uri "A unique identifier for the term and the definition of it's meaning." -[4]: ./glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator are both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123." +[8]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md#authority "URIs for terms reveal the authoritative source for a particular definition, which in our example was example.com." diff --git a/glossarify-md.conf.json b/glossarify-md.conf.json index 803908b7..341e7886 100644 --- a/glossarify-md.conf.json +++ b/glossarify-md.conf.json @@ -4,25 +4,38 @@ "outDir": "../../doc", "glossaries": [ { - "file": "./glossary.md", - "termHint": "★" + "file": "./**/*.md" }, { "file": "./_references.md", + "termHint": " 🌎", + "linkUris": true + }, + { + "file": "./_pages.md", "linkUris": true } ], + "keepRawFiles": [ + "README.md" + ], + "excludeFiles": [ + "node_modules", + ".git" + ], "ignoreCase": true, "linking": { - "paths": "relative", + "baseUrl": "https://github.com/about-code/glossarify-md/blob/master/doc/", + "paths": "absolute", "mentions": "first-in-paragraph", "headingDepths": [ + 1, 2, 3, 4, 5, 6 ], - "limitByAlternatives": 10 + "limitByAlternatives": 5 } } diff --git a/lib/anchorizer.js b/lib/anchorizer.js index c9b67ab6..bded2ace 100644 --- a/lib/anchorizer.js +++ b/lib/anchorizer.js @@ -87,11 +87,11 @@ function anchorizePattern(node, index, parent, slugger, generateFilesConf) { if (match[1]) { // there's a capture group to extract the title title = match[1]; - id = `${slugger.slug(title.substr(0, 20))}`; + id = `${slugger.slug(title.substring(0, 20))}`; } else { // apply default capture group to use the matching pattern itself as the title title = text.match(`(${pattern})`)[1]; - id = `${slugger.slug(title.substr(0, 20))}`; + id = `${slugger.slug(title.substring(0, 20))}`; } title = title .replace(REGEXP_SANITIZE_HTML_ATTR, "") diff --git a/lib/ast/tools.js b/lib/ast/tools.js index 017ea9da..2b8bf6c0 100644 --- a/lib/ast/tools.js +++ b/lib/ast/tools.js @@ -105,7 +105,7 @@ export function getTableHeaders(tableNode) { export function isHtmlComment(node) { return node && node.type === "html" - && node.value.substr(0, 4) === ""; } diff --git a/lib/identifier.js b/lib/identifier.js index 962662cd..2f5fb331 100644 --- a/lib/identifier.js +++ b/lib/identifier.js @@ -66,7 +66,7 @@ export function identifier(context) { .update(url) .digest("hex") .toString() - .substr(0, algorithm[2] || undefined )}`; + .substring(0, algorithm[2] || undefined )}`; idPlain = url; } catch (err) { /* DEFAULT */ diff --git a/lib/importer.js b/lib/importer.js index 9ad70d5c..4773c8f7 100644 --- a/lib/importer.js +++ b/lib/importer.js @@ -4,7 +4,7 @@ import stripMarkdown from "strip-markdown"; import { unified } from "unified"; import { VFile } from "vfile"; import { GlossarifyExportSkos } from "./interop/export.js"; -import { DcTerms, JsonLd, Skos } from "./interop/vocab.js"; +import { DcTerms, DcTermsUri, JsonLd, Skos, SkosUri, GlossarifyMdUri } from "./interop/vocab.js"; import { ExportTypeGlossary } from "./model/export-type-glossary.js"; import { readJsonFile, readTextFile } from "./path/tools.js"; import { beginsWith } from "./text/tools.js"; @@ -27,7 +27,13 @@ const jsonldModuleLoaded = import("jsonld") }; return jsonldModule; }) - .catch((err) => { + .catch(err => { + err.moduleNotFound = true; + return err; + }); + +const csvParserModuleLoaded = import("csv-parse") + .catch(err => { err.moduleNotFound = true; return err; }); @@ -47,17 +53,49 @@ export async function importGlossaries(context) { if (! (importConf && file)) { return Promise.resolve(); } - - const jsonldContextFile = importConf.context || ""; + const acceptContentTypes = { + "jsonld": "application/ld+json" + ,"json": "application/json" + ,"nq": "application/n-quads" + ,"csv": "text/csv" + ,"txt": "text/plain" + }; + const importExternalContextFile = importConf.context || ""; const importFile = importConf.file || ""; - const importContentTypes = [ - "application/json" - ,"application/ld+json" - ,"application/n-quads" - ,"text/plain" - ]; - const {content, contentType} = await readTextFile(importFile, baseDir, importContentTypes); - const glossaryObj = await parse(content, contentType, baseDir, jsonldContextFile, importFile, locale); + const { content, contentType } = await readTextFile(importFile, baseDir, acceptContentTypes); + let glossaryObj; + let jsonImported; + if (/^application\/n-quads/.test(contentType)) { + jsonImported = await parseNquadsToJson(content, contentType); + glossaryObj = await parseJsonLd(jsonImported, baseDir, importExternalContextFile, importFile, locale); + } else if (/^text\/csv/.test(contentType)) { + jsonImported = await parseCsvToJson(content, importFile, glossConf); + glossaryObj = await parseJsonLd(jsonImported, baseDir, importExternalContextFile, importFile, locale); + } else if (/^application\/ld+json/.test(contentType)) { + jsonImported = JSON.parse(content); + glossaryObj = await parseJsonLd(jsonImported, baseDir, importExternalContextFile, importFile, locale); + } else if (/^(application\/json|text\/plain)/.test(contentType)) { + jsonImported = JSON.parse(content); + try { + // Try parsing JSON-LD even though content type indicates a plain JSON file. + // In case 'jsonld' npm module could not be found or has not been installed + // be tolerant, though, and rather assume the plain JSON file matches + // glossarify's own export format terminology, such that no special JSON-LD + // processing is necessary. Import may fail with errors if the assumption doesn't + // hold true. + glossaryObj = await parseJsonLd(jsonImported, baseDir, importExternalContextFile, importFile, locale); + } catch (err) { + if (err.moduleNotFound === true) { + glossaryObj = jsonImported; + console.warn(err); + } else { + throw err; + } + } + } else { + throw new Error("Unknown content type."); + } + try { const vFile = new VFile({ path: file @@ -102,52 +140,96 @@ export async function importGlossaries(context) { * * @param {string} content Data string to parse. * @param {string} baseDir Base directory to look for jsonld external context - * @param {object} jsonldDocFile Filename of user-configured external context - * @param {string} jsonImportFile Name of the file that is being processed (log messages) + * @param {object} externalContextFilename Filename of user-configured external context + * @param {string} jsonFileName Name of the file that is being processed (log messages) * @return {ExportTypeGlossary} Glossary */ -async function parse(content, contentType, baseDir, jsonldDocFile, jsonImportFile, locale) { - - try { - const jsonldModule = await jsonldModuleLoaded; - if (! jsonldModule) { - throw "☛ Optional npm package 'jsonld' not installed." - + " SKOS vocabulary support not available for importing terms.\n"; - } else { - // 1. Parse import data into JSON Document - let jsonDocImported; - if (contentType === "application/n-quads") { - jsonDocImported = await jsonldModule.fromRDF(`${content}`, { format: contentType }); - } else { - // assume "application/json" - jsonDocImported = JSON.parse(content); - } - // 2. Augment imported JSON document with @context if not available - if (jsonldDocFile) { - // ...user configured to use an external JSON-LD context file - const jsonldDoc = await readJsonFile(jsonldDocFile, baseDir); - jsonDocImported = await setExternalLdContext(jsonDocImported, jsonldDoc, jsonldDocFile); - } - if (! jsonDocImported[JsonLd["@context"]]) { - // ... no JSON-LD context. Fall back to use own SKOS mapping context. - console.log(`☛ Note: No JSON-LD @context mapping found. Assuming "${jsonImportFile}" to comply with glossarify-md's export data model.`); - jsonDocImported[JsonLd["@context"]] = GlossarifyExportSkos; - } - // 3. Apply JSON-LD flattening to get flattened data graph - const flattened = await jsonldModule.flatten(jsonDocImported, null); - const ldNodes = flattened[JsonLd["@graph"]] || flattened || []; - // 4. Map data graph onto glossarify-md model by interpreting SKOS model terms - const parsed = skosToGlossary(ldNodes, locale); - return parsed; +async function parseJsonLd(jsonDoc, baseDir, externalContextFilename, jsonFileName, locale) { + const jsonldModule = await jsonldModuleLoaded; + if (! jsonldModule) { + throw "☛ Optional npm package 'jsonld' not found. Assuming import file format matches glossarify-md's export format.\n"; + } else { + // 1. Augment imported JSON document with @context if not available + if (externalContextFilename) { + // ...user configured to use an external JSON-LD context file + const externalContextJson = await readJsonFile(externalContextFilename, baseDir); + jsonDoc = await setExternalLdContext(jsonDoc, externalContextJson, externalContextFilename, jsonFileName); } - } catch (err) { - if (err.moduleNotFound === true) { - console.log(err); - // Assume file to import has glossarify-md export document format... - return JSON.parse(content); - } else { - throw err; + if (! jsonDoc[JsonLd["@context"]]) { + // ... no JSON-LD context. Fall back to use own SKOS mapping context. + console.log(`☛ Note: No JSON-LD @context mapping found. Assuming "${jsonFileName}" to comply with glossarify-md's export data model.`); + jsonDoc[JsonLd["@context"]] = GlossarifyExportSkos; } + // 2. Apply JSON-LD flattening to get flattened data graph + const flattened = await jsonldModule.flatten(jsonDoc, null); + const ldNodes = flattened[JsonLd["@graph"]] || flattened || []; + // 3. Map data graph onto glossarify-md model by interpreting SKOS model terms + const parsed = skosToGlossary(ldNodes, locale); + return parsed; + } +} + +async function parseNquadsToJson(content, contentType) { + const jsonldModule = await jsonldModuleLoaded; + if (! jsonldModule) { + throw "☛ Optional npm package 'jsonld' not installed." + + " Cannot import content type application/n-quads.\n"; + } else { + return await jsonldModule.fromRDF(`${content}`, { format: contentType }); + } +} + +async function parseCsvToJson(content, fileName, glossConf) { + const csvParserModule = await csvParserModuleLoaded; + const {uri, import:importConf } = glossConf; + const {title, dialect, schema} = importConf || {}; + const {delimiter, quoteChar, escapeChar} = dialect || {}; + if (! csvParserModule) { + throw "☛ Optional npm package 'csv-parse' not installed." + + " Cannot import content type text/csv.\n"; + } else { + return new Promise((resolve, reject) => { + let { fields } = schema || { fields: [] }; + let fieldNames = fields.map(f => f.name); + // Assume to have headers embedded if there aren't field names configured. + let hasHeader = fieldNames.length > 0 ? fieldNames : true; + csvParserModule.parse(content, { + bom: true + ,columns: hasHeader + ,ignore_last_delimiters: !!hasHeader + ,delimiter: delimiter || ";" + ,quote: quoteChar + ,escape: escapeChar + ,skip_lines_with_error: true + ,group_columns_by_name: true + ,trim: true + ,skip_empty_lines: true + }, (err, records) => { + if (err) { + err.message = `${fileName}: ${err.message}`; + reject(err); + return; + } + return resolve({ + "@context": { + "@vocab": GlossarifyMdUri + ,"@base": uri + ,"skos": SkosUri + ,"dc": DcTermsUri + ,"title": "dc:title" + ,"records": { + "@container": "@list" + } + } + ,"@id": uri + ,"@type": Skos.ConceptScheme + ,title: title + ,records: records.map(record => { + return { "@type": Skos.Concept,...record }; + }) + }); + }); + }); } } @@ -157,7 +239,7 @@ async function parse(content, contentType, baseDir, jsonldDocFile, jsonImportFil * @param {Object} ldContextDoc A JSON-LD *external context* document to embed into the JSON-Document. * @returns */ -function setExternalLdContext(doc, ldContextDoc, ldContextDocFile) { +function setExternalLdContext(doc, ldContextDoc, ldContextDocFileName, docFileName) { // Merge external JSON-LD context provided via config // into imported JSON data. Note that imported JSON data // might already embed a JSON-LD context. @@ -165,9 +247,9 @@ function setExternalLdContext(doc, ldContextDoc, ldContextDocFile) { let embeddedContext = doc[JsonLd["@context"]]; if (Array.isArray(embeddedContext)) { console.info( - "☛ Imported file provides a JSON-LD embedded context array." - + ` Appending external context at '${ldContextDocFile}'` - + " (provided via config 'glossaries.import.context').\n" + `☛ There's a JSON-LD context array embedded in the imported file '${docFileName}'.` + + ` An external context has been provided in '${ldContextDocFileName}' (via config).` + + " I'm appending the external context to the embedded context array.\n" ); if (Array.isArray(externalContext)) { embeddedContext = [ @@ -180,9 +262,9 @@ function setExternalLdContext(doc, ldContextDoc, ldContextDocFile) { doc[JsonLd["@context"]] = embeddedContext; } else if (embeddedContext) { console.info( - "☛ Imported file declares a JSON-LD context. It will be" - + ` overwritten by an external context at '${ldContextDocFile}'` - + " (provided via config 'glossaries.import.context').\n" + `☛ There's a JSON-LD context embedded in the imported file '${docFileName}'.` + + ` An external context has been provided in '${ldContextDocFileName}' (via config).` + + " I'm overwriting the embedded context with the external context.\n" ); doc[JsonLd["@context"]] = externalContext; } else { diff --git a/lib/linker.js b/lib/linker.js index f1b32e48..af2b056d 100644 --- a/lib/linker.js +++ b/lib/linker.js @@ -23,7 +23,6 @@ export function linker(context) { * @param { {key: IndexEntry[] }} TermDefinitionNodes indexed by value (hash) */ const getTermsSorted = function (indexEntries) { - // let terms = Object.keys(_byAnchor).sort(strComparator); let keys = Object.keys(indexEntries); let result = []; for (let i = 0, len = keys.length; i < len; i++) { diff --git a/lib/path/tools.js b/lib/path/tools.js index fdf18405..a4cdd91e 100644 --- a/lib/path/tools.js +++ b/lib/path/tools.js @@ -290,16 +290,17 @@ export async function readJsonFile(jsonFileNameOrUrl, baseDir) { * * @param {string} textFileNameOrUrl (only https:// or file://) * @param {string} baseDir + * @param {object} contentTypeMap A map with keys denoting acceptable file extensions and values being the respective IANA MIME type to pass in an HTTP Accept header when reading a file from remote. * @returns {Promise<{content: string, contentType: string}>} Promises an object with content and contentType property. */ -export function readTextFile(textFileNameOrUrl, baseDir, contentTypes = []) { +export function readTextFile(textFileNameOrUrl, baseDir, contentTypeMap = {}) { const fileScheme = "file://"; const httpScheme = "http://"; const httpsScheme = "https://"; if (textFileNameOrUrl.match(new RegExp(`^(${httpsScheme}|${fileScheme})`))) { // https:// - return readTextFileUrl(textFileNameOrUrl, contentTypes); - } else if (textFileNameOrUrl.substr(0, httpScheme.length) === httpScheme) { + return readTextFileUrl(textFileNameOrUrl, contentTypeMap); + } else if (textFileNameOrUrl.substring(0, httpScheme.length) === httpScheme) { // http:// return Promise.reject(`Reading files from ${httpScheme} URL not supported. Use ${httpsScheme} or ${fileScheme} URLs or filesystem paths.`); } else { @@ -309,20 +310,13 @@ export function readTextFile(textFileNameOrUrl, baseDir, contentTypes = []) { if (err) { reject(err); } else { - let contentType; - if (textFileNameOrUrl.match(/\.json$/)) { - contentType = "application/json"; - } else if (textFileNameOrUrl.match(/\.jsonld$/)) { - contentType = "application/ld+json"; - } else if (textFileNameOrUrl.match(/\.nq$/)) { - contentType = "application/n-quads"; - } else { - contentType = "text/plain"; - } + const matches = textFileNameOrUrl.match(/\.([a-zA-Z]*)$/); + const fileExt = matches[1] || "txt"; + const contentType = contentTypeMap[fileExt] || "text/plain"; resolve({ contentType, content }); } }; - if (textFileNameOrUrl.substr(0, fileScheme.length) === fileScheme) { + if (textFileNameOrUrl.substring(0, fileScheme.length) === fileScheme) { readFile(textFileNameOrUrl, cb); } else { readFile(path.resolve(baseDir, textFileNameOrUrl), cb); @@ -335,7 +329,7 @@ export function readTextFile(textFileNameOrUrl, baseDir, contentTypes = []) { * @param {string} jsonFileUrl * @param {string[]} contentTypes An array of up to 10 content types in weighted order. */ -function readTextFileUrl(jsonFileUrl, contentTypes = [ "application/json", "text/plain" ]) { +function readTextFileUrl(jsonFileUrl, contentTypeMap) { return new Promise((resolve, reject) => { /* @@ -344,6 +338,7 @@ function readTextFileUrl(jsonFileUrl, contentTypes = [ "application/json", "text * mime/type1, mime/type2;q=0.9, mime/type3;q=0.8, ... * ~~~ */ + const contentTypes = Object.values(contentTypeMap); const contentTypesAccept = contentTypes .slice(0, 9) .map((type, i) => `${type}${i > 0 ? ";q=" + (1.0 - i * 0.1) : ""}`) diff --git a/lib/text/tools.js b/lib/text/tools.js index 0554ec22..22adb028 100644 --- a/lib/text/tools.js +++ b/lib/text/tools.js @@ -12,11 +12,11 @@ export function getHash8(value) { .update(value) .digest("hex") .toString() - .substr(0, 8); + .substring(0, 8); } export function beginsWith(begin = "", str = "") { - return str.substr(0, begin.length) === begin; + return str.substring(0, begin.length) === begin; } /** diff --git a/md/README.md b/md/README.md index df6c2bff..5b73bcc7 100644 --- a/md/README.md +++ b/md/README.md @@ -3,40 +3,35 @@ ![Tests (Functional)](https://github.com/about-code/glossarify-md/workflows/Tests%20(Functional)/badge.svg) ![Nightly Tests (Latest Dependencies)](https://github.com/about-code/glossarify-md/workflows/Tests%20(with%20latest%20deps)/badge.svg) - -[glossarify-md] is a command line tool to help Markdown writers with - -- **Cross-Linking** (primary use case): autolink terms to some definition in a glossary -- **Indexes**: generate indexes from glossary terms and navigate to where they were mentioned -- **Lists**: generate arbitrary lists such as *List of Tables*, *List of Figures*, *List of Listings*, *List of Definitions*, *List of Formulas*, and so forth... - -[vuepress] users might be interested in learning [how to use the tool with vuepress][doc-vuepress]. - +[CommonMark]: https://www.commonmark.org +[doc-book-index]: https://github.com/about-code/glossarify-md/blob/master/doc/gen-book-index.md +[doc-config]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md +[doc-cross-linking]: https://github.com/about-code/glossarify-md/blob/master/doc/cross-linking.md +[doc-extended]: https://github.com/about-code/glossarify-md/blob/master/doc/README.md +[doc-options]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md [doc-paths-and-urls]: https://github.com/about-code/glossarify-md/blob/master/doc/paths-and-urls.md +[doc-syntax-extensions]: https://github.com/about-code/glossarify-md/blob/master/doc/markdown-syntax-extensions.md +[doc-term-attributes]: https://github.com/about-code/glossarify-md/blob/master/doc/term-attributes.md [doc-vocabulary-uris]: https://github.com/about-code/glossarify-md/blob/master/doc/vocabulary-uris.md -[doc-skos-interop]: https://github.com/about-code/glossarify-md/blob/master/doc/skos-interop.md [doc-vuepress]: https://github.com/about-code/glossarify-md/blob/master/doc/use-with-vuepress.md -[doc-syntax-extensions]: https://github.com/about-code/glossarify-md/blob/master/doc/markdown-syntax-extensions.md -[doc-conceptual-layers]: https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md -[doc-config]: https://github.com/about-code/glossarify-md/blob/master/conf/README.md -[CommonMark]: https://www.commonmark.org [GFM]: https://github.github.com/gfm/ [glob]: https://github.com/isaacs/node-glob#glob-primer [glossarify-md]: https://github.com/about-code/glossarify-md -[jsonld]: https://npmjs.com/package/jsonld +[Hugo]: https://gohugo.io [link reference definitions]: https://spec.commonmark.org/0.30/#link-reference-definition -[mdast]: https://github.com/syntax-tree/mdast -[micromark]: https://github.com/micromark/ [pandoc]: https://pandoc.org [pandoc-heading-ids]: https://pandoc.org/MANUAL.html#heading-identifiers -[remark]: https://github.com/remarkjs/remark -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter -[remark-plugins]: https://github.com/remarkjs/awesome-remark -[unified]: https://unifiedjs.com [unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md [vuepress]: https://vuepress.vuejs.org [YAML]: https://yaml.org +[glossarify-md] is a command line tool to help Markdown writers with + +- **Cross-Linking** (primary use case): autolink terms to some definition in a glossary +- **Indexes**: generate indexes from glossary terms and navigate to where they were mentioned +- **Lists**: generate arbitrary lists such as *List of Tables*, *List of Figures*, *List of Listings*, *List of Definitions*, *List of Formulas*, and so forth... + + ## Table of Contents ## Prerequisites @@ -45,16 +40,7 @@ ## Install -#### Option 1: Install *globally*, init config and run: - -~~~ -npm install -g glossarify-md - -glossarify-md --init --new -glossarify-md --config ./glossarify-md.conf.json -~~~ - -#### Option 2 (recommended): Install *locally*, init config and run: +#### Option 1: Install *locally*, init, configure, run (recommended): ~~~ cd ./your-project @@ -64,13 +50,10 @@ npx glossarify-md --init --new --local npx glossarify-md --config ./glossarify-md.conf.json ~~~ -**Optionally:** You might want to set up a shortcut... +> **ⓘ Since 6.3.0** glossarify-md supports a `--watch` mode. -~~~ -npm run glossarify -~~~ -... by adding a run script to your `package.json`: +When installing locally you might want to set up a shortcut by adding a run script to your `package.json`: ~~~json { @@ -80,11 +63,35 @@ npm run glossarify } ~~~ -> **ⓘ Since 6.3.0** glossarify-md supports a `--watch` mode. +Next time you're able to use: + +~~~ +npm run glossarify +~~~ + +#### Option 2: Install *globally*, init, configure, run: + +~~~ +npm install -g glossarify-md + +glossarify-md --init --new +glossarify-md --config ./glossarify-md.conf.json +~~~ ## Configuration -If you've followed the installation instructions you are already set up for a quick start. For customizing your configuration **[see here][doc-config]**. +By following the installation instructions you should be set up with a minimal configuration: + +*Minimal Configuration* +~~~json +{ + "$schema": "./node_modules/glossarify-md/conf/v5/schema.json", + "baseDir": "./docs", + "outDir": "../docs-glossarified" +} +~~~ + +**[More configuration options here][doc-config]**. ## Sample @@ -107,9 +114,9 @@ ${root} `- glossarify-md.conf.json ``` -**Input** +### Input -Your original glossary is a file +Your original glossary is a file with *term definitions* *docs/glossary.md* @@ -121,11 +128,11 @@ Your original glossary is a file A glossary term has a short description. The full description contains both sentences. ``` -Your document files may just use the term *Term* anywhere in text: +The term *Term* may occurs anywhere in the rest of your document files: *./docs/pages/page1.md...* ```md -# Demo +# Document This is a text which uses a glossary Term to describe something. ``` @@ -137,20 +144,20 @@ Then run [glossarify-md] with a [glossarify-md.conf.json](#configuration): npx glossarify-md --config ./glossarify-md.conf.json ~~~ -**Output Results** +### Output Augmented versions of the source files have been written to the output directory: -*./docs-glossarified/pages/page1.md* +*Source: ./docs-glossarified/pages/page1.md* ```md -# [Demo](#demo) +# [Document](#document) This is a text which uses a glossary [Term][1] to describe something. [1]: ../glossary.md#term "A glossary term has a short description." ``` -*Rendered as HTML:* +*When rendered to HTML:* > ## [Demo](#demo) > @@ -159,9 +166,7 @@ This is a text which uses a glossary [Term][1] to describe something. > [1]: #term "A glossary term has a short description." -Headings in glossary files have got an anchor ID and have been made linkable: - -*./docs-glossarified/glossary.md*: +*Source: ./docs-glossarified/glossary.md*: ```md # [Glossary](#glossary) @@ -171,34 +176,33 @@ Headings in glossary files have got an anchor ID and have been made linkable: A glossary term has a short description. The full description contains both sentences. ``` -*Rendered as HTML*: +*When rendered to HTML*: > ## [Glossary](#glossary) > > ### [Term](#term) > > A glossary term has a short description. The full description contains both sentences. -## What's not Linked +## What's not being linkified -Some syntactic positions of a term occurrence are **excluded** from being linked to the glossary. Terms are not linkified when part of: +Some syntactic positions of a term occurrence are **excluded** from being linked to the glossary, for example when the term occurs in: +- HTML `text` - Headlines `#` - (Markdown) links `[]()` - Preformatted blocks ` ```, ~~~ ` - Blockquotes `>` -- HTML `text` + - 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. -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. -> **ⓘ Tip:** Wrap a word into some pseudo HTML tag like e.g. `word` to mark a word for exclusion from [term-based auto-linking][cross-linking]. +> **ⓘ Tip:** Wrap a word into some pseudo HTML tag like e.g. `word` to mark a word for exclusion from [term-based auto-linking][doc-cross-linking]. ## Aliases and Synonyms [alias]: #aliases-and-synonyms [aliases]: #aliases-and-synonyms -[term-attributes]: #aliases-and-synonyms -Aliases can be added by what we call *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: +Aliases 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: *glossary.md with a term attribute `aliases`:* ```md @@ -219,7 +223,7 @@ In the output files aliases will be linked to their related term: [Cats](./glossary.md#cat) and kitten almost hidden spotting mouses in their houses. [Andreas Martin] ``` -> **ⓘ Note:** [YAML] syntax is *case-sensitive* as well as *sensitive to tabs and whitespaces*. In general term attributes will be lowercase. You may find that an uppercase `Aliases: ` term attribute works as well. This is going to be the only attribute for which an uppercase name remains supported *for backwards compatibility*. +> **ⓘ Note:** [YAML] syntax is *case-sensitive* as well as *sensitive to tabs and whitespaces*. In general term attributes will be lowercase. That's all you need to know for a quick start. Continue reading to learn about additional features. @@ -234,13 +238,11 @@ That's all you need to know for a quick start. Continue reading to learn about a Glossaries 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. -> **ⓘ Since v5.0.0**: `file` can also be used with a [glob] pattern. More see [Cross-Linking]. - ## Multiple Glossaries [multiple-glossaries]:#multiple-glossaries -Sometimes you might whish to have multiple glossaries. For example as a Requirements Engineer you may not just have a glossary of business terms but also a requirements catalogue: +Sometimes you might whish to have multiple glossaries: *glossarify-md.conf.json* @@ -261,7 +263,9 @@ Sometimes you might whish to have multiple glossaries. For example as a Requirem ``` -By adding *requirements.md* to the list of glossaries every use of *REQ-1* or *REQ-2* in documents gets linked to the requirements glossary. To navigate the opposite direction from a requirement to sections where those got mentioned you can generate a [Book Index](#book-index). +By adding *requirements.md* to the list of glossaries every use of *REQ-1* or *REQ-2* in documents gets linked to the requirements glossary. To navigate the opposite direction from a requirement to sections where those got mentioned you can generate a [Book Index][doc-book-index]. + +**Since v5.0.0** `file` can also be used with a [glob] pattern. This way each markdown file matching the pattern is considered a glossary. More see [Cross-Linking][doc-cross-linking]. ## Sorting Glossaries @@ -284,403 +288,17 @@ Internally, glossarify-md uses `Intl.Collator` and falls back to `String.localeC } ``` -The 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): - -## Cross Linking - -[cross-linking]: #cross-linking - -> **ⓘ Since: v5.0.0** - -### Term-Based Auto-Linking - -*Term-based auto-linking* is what we've seen so far. It is to assume headings in markdown files called *glossaries* are *terms* that whenever being mentioned in text are being turned into a link to the glossary section where they have been defined as a term. - -**Since v5.0.0** we've added a few features which let us evolve that principle into a more generic means of cross-linking beginning with support for [glob] patterns in `glossaries.file`. For example with ... - -```json -"glossaries": [ - { "file": "./**/*.md"} -] -``` - -... you can turn any `*.md` file being processed into a "glossary". Now *all* document headings are considered terms. Mentioning the heading or an [alias] alike turns the phrase into a link to that section. - -> **ⓘ Too many links?** -> -> What might happen with *globs* is, that you might feel that *too many links* are being generated disturbing the reading experience. If this is an issue for you explore options like [`linking.mentions`](#linkingmentions), [`linking.headingDepths`](#linkingheadingdepths) or [`linking.limit*`](#linkinglimitbyalternatives) options. - -> **ⓘ Note:** When there are multiple `glossaries: []` entries with a `{ file: ... }` glob or path and a given file matches more than one entry then `glossaries` options of the entry latest in the array will apply. Though avoid too many glob patterns or patterns whose file sets overlap as the effects on the output get increasingly hard to understand, otherwise. - -### Identifier-based Cross-Linking - -If the same section heading exists more than once then you might want to link to one heading in particular. While you should consider using an [alias] to make use of term-based auto-linking, there might be situations where you whish to have manually declared links. - -**Since v5.0.0** we've added support for manual cross-linking through [pandoc's concept of heading ids][pandoc-heading-ids]. These allow you to assign identifiers which are more stable for referencing than auto-generated IDs derived from the heading phrase (slugs). - -> **ⓘ Note:** Pandoc's identifier syntax is not standardized in [CommonMark]. - -[Sample]: document `./pages/page1.md` declares a heading - -*/pages/page1.md* -~~~md -## User Story {#s-241} -~~~ - -with heading-id `#s-241`. **Given that `#s-241` is *unique* across all documents** you can use it as a link reference: - -~~~md -[any phrase](#s-241) -~~~ - -In any file being processed [glossarify-md] will resolve the actual path to the definition: - -*/README.md* -~~~ -[any phrase](./pages/page1.md#s-241) -~~~ - -*/pages/page2.md* -~~~ -[any phrase](./page1.md#s-241) -~~~ - -## Generating Files - -### Book Index - -*glossarify-md.conf.json* - -```json -"generateFiles": { - "indexFile": { - "file": "./book-index.md", - "title": "Book Index" - } -} -``` - -This option will generate a single book index file `./book-index.md` with glossary terms and links to book sections in which they have been mentioned. By default items will be grouped *by section of occurrence* using the section heading as a group title. You can disable or affect granularity of section-based grouping using: - -```json -"indexing": { - "groupByHeadingDepth": 0 -} -``` - -> **ⓘ Note**: The `groupByHeadingDepth` option also affects grouping of list items in [Lists](#lists). - -Let's assume you have multiple glossaries and you want to create separate book indexes from terms of those glossaries. **Since v5.1.0** you can use `indexFiles` (plural) like this: - -```json -"generateFiles": { - "indexFiles": [{ - "title": "Book Index for Glossary 1", - "file": "./book-index-1.md", - "glossary": "./glossary-1.md" - },{ - "title": "Book Index for Glossary 2", - "file": "./book-index-2.md", - "glossary": "./glossary-2.md" - }] -} -``` - -> **ⓘ Note:** If you plan on translating markdown to HTML, e.g. with [vuepress](https://vuepress.vuejs.org), be aware that a file `index.md` will translate to `index.html` which is typically reserved for the default HTML file served under a domain. We recommend you choosing another name. - -### Lists - -You can generate **arbitrary lists from HTML elements with an `id` attribute** and an element *classifier* to compile similar elements into the same list. - - -*Example: Markdown document with a video element* -```md -More details see our video tutorial: - - -``` -Then to generate a *List of Videos* from all elements of `class="video"` add to your *glossarify-md.conf.json*: - -```json -"generateFiles": { - "listOf": [{ - "class": "video", - "title": "List of Videos", - "file": "./videos.md" - }] -} -``` - -After running glossarify-md there will be a file: - -*docs-glossarified/videos.md (generated)* -> ## List of Videos -> -> - [Tutorial Part 1](#video-tutorial-part-1) - -You can **type less** when prefixing ids with your list classifier: - -~~~md - -~~~ - -Without a `title` attribute the tool attempts to derive a list item label from an elements inner text content: - -~~~md - -~~~ - -Use *invisible* HTML anchors to generate lists from and navigate to text content: - -~~~md - -This is not a video tutorial but a textual tutorial. The body of text can be navigated to from a List of Tutorials and uses the classifier *tutorial*. -~~~ - -> **ⓘ Note:** If you find the browser not scrolling correctly when navigating lists on GitHub, please read [Addendum: Lists in GitHub Repos](https://github.com/about-code/glossarify-md/blob/master/doc/lists-on-github.md). - - - -### List of Figures - -So far we used [`listOf`](#lists) to generate a list from *HTML elements* in Markdown. Writing HTML can be annoying, particularly if there is handier Markdown syntax for the elements to be listed. This is where -`listOfFigures` and [`listOfTables`](#list-of-tables) fit in. It is a shortcut which makes [glossarify-md] generate the HTML anchor itself from Markdown's image syntax: - -```md -![List item Label](./figure.png) -``` - -Then you may only need to use HTML for dynamically rendered figures, e.g. a [PlantUML](https://plantuml.com) diagram: - -````md -
Dynamically Rendered Diagram
- -```plantuml -@startuml -... your PlantUML diagram code ... -@enduml -``` -```` - -To compile both figures into the same list one way to configure [glossarify-md] is to declare a `listOf` class *figure* (for HTML elements) and tell `listOfFigures` (for `![]()` images) to use the same classifier *figure*: - -*glossarify-md.conf.json* (since v5.0.0) - -```json -"generateFiles": { - "listOf": [{ - "class": "figure", - "title": "List of Figures", - "file": "./figures.md" - }], - "listOfFigures": { - "class": "figure" - } -} -``` - -This configuration which would allow you to also choose a shorter classifier like *fig* is the default, though. Therefore, if you are fine with ***figure* as the default classifier** you can omit `listOf` and just use: - -*glossarify-md.conf.json* - -```json -"generateFiles": { - "listOfFigures": { - "title": "List of Figures", - "file": "./figures.md" - } -} -``` - -### List of Tables - -`listOfTables` like [`listOfFigures`](#list-of-figures) is a shortcut alternative to HTML anchors with a default [`listOf`](#lists) classifier ***table***: - -*glossarify-md.conf.json* - -```json -"generateFiles": { - "listOfTables": { - "title": "Tables", - "file": "./tables.md" - } -} -``` - -In contrast to images Markdown tables have no notion of a table caption. To render a list item for a table [glossarify-md] tries to infer a list item label. - -One such inference looks at the **paragraph preceding the table**. If it **ends with an *emphasized* phrase** and the phrase itself is **terminated by a colon** then the tool uses that phrase as the item label: - - - -```md -[...] which we can see from the *table of average prices by article category:* - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -But the phrase could also be it's own distinct paragraph: - - -```md -[...] which we can see from the average price by article category. - -*Average prices by category:* - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -**Since v3.4.0** there has also been support for *invisble* table captions using *HTML comment syntax*: - - -```md - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -The result for the tables above will be: - -> ## List of Tables -> -> - [Table of average prices by article category](#table-of-average-prices-by-article-category) -> - [Average prices by category](#average-prices-by-category) -> - [Average Prices by Article Category](#avg-prices) - - -**Since v5.0.0** and the introduction of `listOf` all the previous examples will make [glossarify-md] annotate the table with an HTML anchor. So while not recommended due to verbosity, you could of course also just add an HTML anchor yourself, like described in [`listOf`](#lists): - -```md - - -| Category | Description | Price Avg. | -| -------- | ----------- | ---------- | -| 1 | Video Game | $35.66 | -| 2 | Film | $10.13 | -| 3 | Book | $23.45 | -``` - -> **ⓘ Note:** If [glossarify-md] can't find a list item label by any of the above means it will fall back to rendering a list item -> 1. using the table headers separated by comma, -> 1. or if no headers, using the closest section heading -> 1. or if no section heading, using the file name. - - +The `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): -### Lists from Regular Expressions -**Since v5.2.0** you can use `listOf` with a regular expression pattern. Like `listOfFigures` and `listOfTables` it is meant to be a shortcut to save you from annotating Markdown with HTML elements yourself. - -Let's assume you are writing a book with tasks to be accomplished by your readers. You would like to compile a *List of Tasks* in that book. You decided to use a conventional pattern which prefixes tasks with a phrase **Task:** and ends them with an exclamation mark *!* - -*Document.md* -~~~md -Some text [...] - -**Task:** Clap your hands! -~~~ - -You can then generate a *List of Tasks* with a configuration like this: -~~~md -{ - "generateFiles": { - "listOf": [ - { - "class": "task", - "title": "Tasks in this Book", - "file": "./list-of-tasks.md", - "pattern": "Task: ([a-zA-Z0-9].*)!" - } - ] - } -} -~~~ - -If the regular expression (RegExp) matches text in a paragraph, then *the paragraph* will be annotated with an anchor for `listOf`. Our RegExp has a Capture Group in braces `()`. Text matching the group pattern will become the list item label, so *Clap your hands* in the example because `Task:` and exclamation mark `!` are not part of the group. - -> **ⓘ When to consider "markdown syntax" in the RegExp**: -> -> You may noticed that the RegExp above doesn't assume *Task:* to be written between "bold" star markers `**`. The expression won't be matched against the input *you* wrote but against *plain text* cleaned from symbols contributing to [CommonMark] or [GFM] syntax. -> -> In case you use another Markdown flavor see our addendum on [Markdown Syntax Extensions][doc-syntax-extensions]. Without a proper plug-in its syntactical elements are likely considered plain text, too. Then they need to be taken care of in the RegExp to make it match. - -## Structured Export and Import -[doc-export-import]: #structured-export-and-import -[SKOS]: https://w3.org/skos - -**Since v6.0.0** glossary terms can be exported to a structured JSON format (file extension `.json`). When [jsonld] is installed alongside glossarify-md then terms can also be exported to RDF N-Quads (file extension `.nq`). - -*glossarify-md.conf.json* (generates ./glossary.json) -~~~json -{ - "glossaries": [{ - "uri": "http://basic.org/vocabulary/#", - "file": "./glossary.md", - "export": { - "file": "./glossary.json" - } - }] -} -~~~ - -Declare a glossary `uri` when exporting. It will make [glossarify-md] assign each term a *uniform resource identifier* by combining the glossary's `uri` with a term's book-internal identifier (see [`headingIdAlgorithm`][headingIdAlgorithm]). Note that URIs are not required to resolve to some web page but *can* do so. More on the idea behind URIs read [here][doc-vocabulary-uris]. You can import terms the same way using `import` instead. - -*glossarify-md.conf.json* (generates ./glossary.md): -~~~json -{ - "glossaries": [{ - "uri": "http://basic.org/vocabulary/#", - "file": "./glossary.md", - "import": { - "file": "./glossary.json" - } - }] -} -~~~ - -> ⚠ **Important:** [glossarify-md] is able to import JSON glossaries from a remote location using `https`. While it will try to remove any Markdown and HTML from imported term definitions using [strip-markdown](https://npmjs.com/package/strip-markdown) it can only do so after `JSON.parse()`. As a rule of thumb never import from untrusted sources and assume that any files from a remote location could enable a remote entity to embed malicious code into outputs or execute such code in the runtime context of [glossarify-md]. Consider importing files statically after review. - -Advanced topics on importing and exporting can be found [here](https://github.com/about-code/glossarify-md/blob/master/doc/skos-interop.md). +## [Advanced Topics][doc-extended] +- Importing and exporting terms +- Generating files, such as a book index, lists of figures, etc. +- Cross-Linking more than just terms +- Using glossarify-md with other tools, like [vuepress], [pandoc] or [Hugo] +- Dealing with non-standard Markdown Syntax via Plug-ins (e.g Frontmatter) +- [...and more][doc-extended] ## Node Support Matrix @@ -694,414 +312,11 @@ The term *support* refers to *runs on the given platform* and is subject to the | 12 LTS | v3, v4, v5 | | | 10 LTS | v2, v3, v4 | | -## Options - -[Options]: #options - -#### `baseDir` - -- **Range:** `string` - -Path to directory where to search for the glossary and markdown files. All paths in a config file except for `$schema` will be relative to *baseDir*. *baseDir* itself and `$schema` are relative to the location of the config file. - -#### `excludeFiles` - -- **Range:** `string[]` - -Paths or Glob-Patterns of files to exclude. Excluded files will be excluded from being copied to `outDir` where they would be processed. Use [`keepRawFiles`](#keeprawfiles) if you want to have them copied to `outDir` but *ignored* by glossarify-md. - -#### `generateFiles` - -- **Range:** `Object` -~~~ -{ - indexFile: {}, - listOf: [], - listOfFigures: {}, - listOfTables: {} -} -~~~ - -#### `generateFiles.indexFile` - -[doc-config-indexFile]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-generatefiles-properties-indexfile.md - -- **Range:** `{file: string, [title: string], [hideDeepLinks: boolean]}` ([details][doc-config-indexFile]) -- **Since:** v3.0.0 - -Generates an index of glossary terms with links to files in which they have been mentioned. - -#### `generateFiles.indexFiles` - -[doc-config-indexFiles]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-generatefiles-properties-indexfiles-items.md - -- **Range:** `Array<{file: string, glossary: string, [title: string], [hideDeepLinks: boolean]}>` ([details][doc-config-indexFiles]) -- **Since:** v3.0.0 - -Similar to `indexFile` but allows for generating multiple index files, e.g. one per glossary. - -#### `generateFiles.listOf` - -[doc-config-listOf]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-generatefiles-properties-listof-items.md - -- **Range:** `Array<{class: string, file: string, [title: string]}>` ([details][doc-config-listof]) -- **Since:** v3.5.0 - -If available, generates a list from HTML anchors exposing the configured `class` attribute. - -#### `generateFiles.listOfFigures` - -- **Range:** `{file: string, [title: string, class: string]}` -- **Since:** v3.3.0 - -Generates a list of figures with links to sections where the figures have been mentioned. - -#### `generateFiles.listOfTables` - -- **Range:** `{file: string, [title: string, class: string]}` -- **Since:** v3.4.0 - -Generates a list of tables. - -#### `glossaries` - -- **Range:** `Array` -~~~ -[ - { - file: string, - termHint: string, - sort: string], - uri: string, - linkUris: boolean, - showUris: boolean|string, - import: {}, - export: {}, - } -] -~~~ -- **Default:** `[{ "file": "./glossary.md", "termHint": "" }]` - -A list of glossary configuations, each with a path to the glossary file. Every -glossary may have an optional *termHint*. A *termHint* is a symbol character -being appended to term occurrences in order to indicate which glossary or -category a term belongs to. A term hint may be any UTF-8 character or character -sequence. If you would like to have the glossary sorted provide a *sort* direction -`"asc"` or `"desc"`. - -#### `glossaries[].export` - -[doc-config-export]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-glossaryfile-properties-export-oneof-0.md - -- **Range:** `{ file: string [, context: string]} | Array<{ file: string [, context: string]}>` ([details][doc-config-export]) -- **Since:** v6.0.0 - -Export markdown terms in a structured JSON format. More read [here][doc-export-import]. - -#### `glossaries[].import` - -[doc-config-import]: https://github.com/about-code/glossarify-md/blob/master/conf/v5/doc/schema-defs-glossaryfile-properties-import.md - -- **Range:** `{ file: string [, context: string]}` ([details][doc-config-import]) -- **Since:** v6.0.0 - -Import terms from a structured JSON format and generate a markdown glossary from it. For an example see [here][doc-export-import]. - -#### `glossaries[].linkUris` - -- **Range:** `boolean` -- **Default:** `false` -- **Since:** v6.0.0 - -When `true`, occurrences of glossary terms found in text will no longer be linked with the markdown glossary file but with an external definition on the web using a term's URI. The given glossary file will serve as a data source for a link title providing a short tooltip and may still be found from [indexFiles](#generatefilesindexfiles). - -#### `glossaries[].showUris` - -- **Range:** `boolean|string` -- **Default:** `false` -- **Since:** v6.0.0 - -When being `true` or being a template string with a placeholder `${uri}` then render term URIs in glossaries generated from [imported][doc-export-import] terms. - -#### `glossaries[].uri` - -See also [Vocabulary URIs][doc-vocabulary-uris]. - -#### `ignoreCase` - -- **Range:** `boolean` - -When true any occurrence of a term will be linked no matter how it was spelled. - -#### `includeFiles` - -- **Range:** `string[]` - -Paths or Glob-Patterns for files to include. Default: `.` (includes all Markdown files within the current directory and its subdirectories). See also [`excludeFiles`](#excludefiles) and ([`keepRawFiles`](#keeprawfiles)). - -#### `indexing` - -- **Range:** `Object` -~~~ -{ - headingDepths: number[], - groupByHeadingDepth: number, -} -~~~ - -#### `indexing.groupByHeadingDepth` - -- **Range:** `number` in [1-6] -- **Default:** 6 -- **Since:** v3.4.0 - -This option affects outputs generated with `generateFiles`. By default when -indexing terms and markdown elements they are being grouped by the heading of -the section they've been found in. In larger books with many sections and -subsections this can lead to Index files or *Tables of X* with a lot of group -headings (many representing sub- and subsubsections). Yet often it's enough for -an Index to only list the chapter or higher-level sections where some term or -element has been found in. This option allows to set the depth by which -elements shall be grouped where `1` refers to chapters (`#` headings). - -#### `indexing.headingDepths` - -- **Range:** `number[]` in 1-6 -- **Default:** `[1,2,3,4,5,6]` -- **Since:** v5.0.0 - -An array with items in a range of 1-6 denoting the depths of headings that should be indexed. Excluding some headings from indexing is mostly a performance optimization, only. You can just remove the option from your config or stick with defaults. Change defaults only if you are sure that you do not want to have cross-document links onto headings at a particular depth, no matter whether the link was created automatically or written manually. Default is `[1,2,3,4,5,6]`. - -The relation to [`linking.headingDepths`](#linkingheadingdepths) is that *this* is about *knowing the link targets* whereas the latter is about *creating links automatically ...based on knowledge about link targets*. Yet, indexing of headings is further required for existing (cross-)links like `[foo](#heading-id)` and resolving the path to where a heading with such id was declared, so for example `[foo](../document.md#heading-id)`. - -#### `i18n` - -- **Range**: `Object` -~~~ -{ - locale: string, - [localeMatcher: string], - [caseFirst: string], - [ignorePunctuation: boolean], - [numeric: boolean], - [sensitivity: string], - [usage: string] -}` -~~~ - -Locale options to control [sorting](#sorting-glossaries). See [`Intl.Collator`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Collator/Collator). - -#### `keepRawFiles` - -- **Range:** `string[]` - -Paths or Glob-Patterns for Markdown files to copy to `outDir` but keep there as they are without -glossarifying and linking. Non-markdown files won't be processed anyways, so no need to add those. - -#### `linking` - -- **Range:** `Object` - -~~~ -{ - baseUrl: string, - byReferenceDefinition: boolean, - paths: "relative" | "absolute", - pathComponents: ["path", "file", "ext"], - pathRewrites: {}, - mentions: "all" | "first-in-paragraph", - headingAsLink: boolean, - headingDepths: number[], - headingIdAlgorithm: "github" | "md5" | "md5-7" | "sha256" | "sha256-7", - headingIdPandoc: boolean, - limitByAlternatives: number - limitByTermOrigin: ["self", "parent", "sibling", "child", "parent-sibling"] -} -~~~ - -#### `linking.baseUrl` - -- **Range:** `string` - -URL to prepend to links. Only effective with `linking.paths: "absolute"`. In most situations, e.g. when hosting markdown files in a repository or processing markdown files with an HTML converter omitting a pre-defined `baseUrl` and using `linking.paths: "relative"` is likely to work better. - -#### `linking.byReferenceDefinition` - -- **Range:** `boolean` -- **Default:** `true`, -- **Since:** v6.0.0 - -Whether to convert inline-links to [link reference definitions] (size-efficient). - -#### `linking.headingAsLink` - -- **Range:** `boolean` -- **Default:** `true` -- **Since:** v6.0.0 - -Whether to linkify headings. Note that some Markdown-to-HTML renderers need headings to be linkified in order to be rendered URL-addressable and navigable. Others like [pandoc] don't need linkified headings but special syntax. - -See also: - -- [`linking.headingIdPandoc`](#linkingheadingidpandoc) - -#### `linking.headingDepths` - -- **Range:** `number[]` in 1-6 -- **Default:** `[2,3,4,5,6]` -- **Since:** v5.0.0 - -Use this option to select markdown heading depths which should be considered terms or sections for cross-linking. For example, to only consider headings `## text` at depth 2 or `### text` at depth 3 but not at depths 1 and 4-6 provide an array `[2,3]` - -> **ⓘ Note:** Headings at the given depths must be indexed. So they must be in the set of [`indexing.headingDepths`](#indexingheadingdepths). - - -#### `linking.headingIdAlgorithm` - -[headingIdAlgorithm]: #linkingheadingidalgorithm - -- **Range:** `"github" | "md5" | "md5-7" | "sha256" |"sha256-7"` -- **Default:** `"github"` -- **Since:** v6.0.0 - -Algorithm to use for generating heading identifiers used as `#` URL-fragment ("slugs"). Option value `"github"` will only guarantee *uniqueness per file* whereas `md5` and `sha256` options will generate a hash *unique in the fileset*. The hash value will depend on - -~~~ -hash ( - glossary file path, - glossary file name without file extension, - glossary uri, - github-slugger(term), - baseUrl -) -~~~ - -where `baseUrl` will be used only if there's no glossary uri. The `*-7` hashsum variants truncate a hash to at most 7 symbols which are still unlikely to collide in normal books. - -#### `linking.headingIdPandoc` - -- **Range:** `boolean` -- **Default:** false -- **Since:** v6.0.0 - -Since v5 there has been support for *parsing* pandoc-style heading IDs from input markdown. In v6 we added support for *writing* pandoc-style `{#id}` identifiers to output markdown to facilitate postprocessing with [pandoc]. - -> **ⓘ Note:** Pandoc's identifier syntax is not standardized in [CommonMark]. - -See also - -- [`linking.headingIdAlgorithm`](#linkingheadingidalgorithm) -- [`linking.paths`](#linkingpaths) - -#### `linking.limitByAlternatives` - -- **Range:** `number[]` in -95 - +95 -- **Default:** 95 -- **Since:** v5.0.0 - -Control how a term occurrence is linkified if there are *multiple definitions* of a term: - -- **positive value**: the system *creates links to alternative definitions but no more than `x` links*. -- **negative value**: the system does *not create a term-link at all once there are more than `x` alternative definitions* of a term or heading. -- **zero**: create a link but to a single out of all definitions, only - - -#### `linking.limitByTermOrigin` - -- **Range:** `string[]` in `["self", "parent", "sibling", "child", "parent-sibling"]` -- **Default:** `[]` -- **Since:** v6.1.0 - -Limits linkification based on the file hierarchy of a book project. For example, `["parent", "sibling", "self"]` causes a term occurrence being linkified only - -- when a term has been defined in a glossary in a parent directory (`"parent"`) -- when it has been defined in a glossary next to the document file (`"sibling"`) -- or within the glossary itself (`"self"`). - -The option allows for a hierarchy of glossaries e.g. a top-level glossary for common terms linked throughout a book and glossaries whose terms are being linked within a particular (sub-)directory/section branch, only. It may also provide a means of limiting auto-linking when the [`glossaries`](#glossaries) option is used with `file` wildcard patterns. Enumerating all elements is equivalent to keeping the array empty. It will make glossarify-md link each glossary term in every document. Defaults to `[]`. - - -#### `linking.mentions` - -- **Range:** `"all" | "first-in-paragraph"` -- **Default:** `"all"` -- **Since:** v5.0.0 - -By default every mention of a term will be linkified. Sometimes this can -result in too much links affecting readability. This option provides finer -control of linkify behavior. - - -#### `linking.paths` - -[opt-linking]: #linkingpaths - -- **Range:** `"relative" | "absolute" | "none" ` -- **Default:** `"relative"` - -Whether to create absolute or relative link-urls to the glossary. - -> **Important:** Using `"absolute"` without a `baseUrl` will produce an absolute file system path which you might not want to publish. - -#### `linking.pathComponents` - -- **Range:** `string[] with "path", "file", "ext"` -- **Default:** `["path", "file", "ext"]` -- **Since:** v6.0.0 - -Allows to tweak which components of a file path should make it into auto-generated links. Examples: - -- `["path", "file", "ext"]` => `./glossary/default.md#term` -- `["path", "file"]` => `./glossary/default#term` -- `["file"]` => `default#term` - -Use `linking.paths: "none"` if you would like to have a fragment (`#`) but no path components. - -#### `linking.pathRewrites` - -- **Range:** `{ [key: string]: string | string[] }` -- **Default:** `{}` -- **Since:** v6.2.0 - -Key-Value map where *Value* is a single search string or an array of strings or regular expressions (RegExp) and *Key* is the replacement/rewrite string. See also [Paths and Urls][doc-paths-and-urls]. - -#### `outDir` - -- **Range:** `string` - -The directory where to write output files to. - -> **Important:** using `.` or `./` is going to overwrite your input files. Only do this on a copy of your input -> files or if you are able to roll back any changes or if you know the outcome satisfies your needs. - -The recommendation is to write outputs to a separate directory such as `../out` or `../target` or `../docs-glossarified`. - - -#### `outDirDropOld` - -- **Range:** `boolean` - -If `true` remove old `outDir` before writing a new one, otherwise overwrite files. Drops orphan files that have intentionally been removed from `baseDir`. - -#### `reportNotMentioned` - -- **Range:** `boolean` - -Report on terms which exist in a glossary but have neither been mentioned directly nor with any of its aliases. - -#### `unified` - -[opt-unified]: #unified - -- **Range:** `{ rcPath: string } | { settings: object, plugins: object|array }` - -Extended [unified configuration][unified-config]. See also [Markdown Syntax Extensions][doc-syntax-extensions]. - ## Special Thanks go to - [John Gruber](https://daringfireball.net/projects/markdown/), author of the Markdown syntax - [John MacFarlane et al.](https://github.com/commonmark-spec), initiators and authors of the CommonMark specification -- [Titus Wormer](https://github.com/wooorm), author of [unifiedjs](https://unifiedjs.com/), [remarkjs](https://github.com/remarkjs) and many more -- and all the other great people publishing modules of value to the tool - directly or transitively. +- [Titus Wormer](https://github.com/wooorm), author of [unifiedjs](https://unifiedjs.com/), [remarkjs](https://github.com/remarkjs) and so much more +- All the other great people publishing modules of value for the tool, be it directly or transitively. ## License diff --git a/md/doc/README.md b/md/doc/README.md index 78f5e254..63bd718d 100644 --- a/md/doc/README.md +++ b/md/doc/README.md @@ -1,8 +1,20 @@ [doc-cli]: ./cli.md +[doc-config]: ../conf/README.md +[doc-cross-linking]: ./cross-linking.md +[doc-cross-linking-auto]: ./cross-linking.md#term-based-auto-linking +[doc-cross-linking-id]: ./cross-linking.md#identifier-based-cross-linking +[doc-cross-linking-tree]: ./cross-linking.md#tree-scoped-linking [doc-dev-conceptual-layers]: ./conceptual-layers.md [doc-dev-node-types]: ../lib/ast/with/node-type.md -[doc-config]: ../conf/README.md +[doc-export]: ./export.md +[doc-gen-book-index]: ./gen-book-index.md +[doc-gen-lists]: ./gen-lists.md +[doc-gen-lists-of-figures]: ./gen-lists.md#list-of-figures +[doc-gen-lists-of-tables]: ./gen-lists.md#list-of-tables +[doc-gen-lists-from-regexp]: ./gen-lists.md#lists-from-regular-expressions [doc-glossary]: ./glossary.md +[doc-import]: ./import.md +[doc-install]: ./install.md [doc-lists-on-github]: ./lists-on-github.md [doc-path-rewriting]: ./paths-and-urls.md [doc-plugins]: ./plugins.md @@ -18,57 +30,73 @@ # Documentation -Alternative Table of Contents for [README.md]. -Sections marked with * describe advanced topics *not* mentioned in [README.md] (root). +Extended Documentation covering all of [README.md] (marked with *) and more... Setup -- [Install](../README.md#install) + +- [Install][doc-install] * - [Configure][doc-config] -- [Command Line Interface*][doc-cli] -- [Node Support Matrix](../README.md#node-support-matrix) +- [Command Line Interface][doc-cli] +- [Node Support Matrix](../README.md#node-support-matrix) * Glossary Basics -- [Basic Glossary Example](../README.md#sample) -- [Aliases and Synonyms](../README.md#aliases-and-synonyms) - - [Term Attributes](./term-attributes.md)* -- [Term Hints](../README.md#term-hints) -- [Multiple Glossaries](../README.md#multiple-glossaries) -- [Sorting Glossaries](../README.md#sorting-glossaries) + +- [Basic Glossary Example](../README.md#sample) * +- [Aliases and Synonyms](../README.md#aliases-and-synonyms) * +- [Term Hints](../README.md#term-hints) * +- [Multiple Glossaries](../README.md#multiple-glossaries) * +- [Sorting Glossaries](../README.md#sorting-glossaries) * +- [Term Attributes](./term-attributes.md) Book Writing -- [Cross Linking](../README.md#cross-linking) - - [Term-Based Auto-Linking](../README.md#term-based-auto-linking) - - [Identifier-based Cross-Linking](../README.md#identifier-based-cross-linking) -- [References*][doc-references] -- [Book Index](../README.md#book-index) -- [Lists](../README.md#lists) - - [List of Figures](../README.md#list-of-figures) - - [List of Tables](../README.md#list-of-tables) - - [Lists from Regular Expressions](../README.md#lists-from-regular-expressions) +- [Cross Linking][doc-cross-linking] + - [Term-Based Auto-Linking][doc-cross-linking-auto] + - [Identifier-based Cross-Linking][doc-cross-linking-id] + - [Tree-Scoped Linking][doc-cross-linking-tree] +- [References][doc-references] + +Generating Files + +- [Book Index][doc-gen-book-index] +- [Lists][doc-gen-lists] + - [List of Figures][doc-gen-lists-of-figures] + - [List of Tables][doc-gen-lists-of-tables] + - [Lists from Regular Expressions][doc-gen-lists-from-regexp] Publishing -- [Using glossarify-md with vuepress*][doc-with-vuepress] -- [Using glossarify-md with pandoc*][doc-with-pandoc] -- [Using glossarify-md with Hugo*][doc-with-hugo] -- [Paths and URLs*][doc-path-rewriting] -Exporting and Importing Terms -- [Basics](../README.md#structured-export-and-import) -- [URIs as Identifiers for Definitions of Meaning*][doc-vocabulary-uris] -- [Interoperability with SKOS and JSON-LD*][doc-skos-interop] +- [Paths and URLs][doc-path-rewriting] +- [Using glossarify-md with vuepress][doc-with-vuepress] +- [Using glossarify-md with pandoc][doc-with-pandoc] +- [Using glossarify-md with Hugo][doc-with-hugo] + +Importing and Exporting Terms + +- [Import][doc-import] +- [Export][doc-export] +- [URIs as Identifiers for Definitions of Meaning][doc-vocabulary-uris] +- [Interoperability with SKOS and JSON-LD][doc-skos-interop] Dealing with Non-Standard Markdown Syntax -- [Markdown Syntax Extensions*][doc-syntax-extensions] -- [Installing Syntax Plug-ins*][doc-plugins] -Glossary -- [Glossary*][doc-glossary] (Terms of glossarify-md) +- [Markdown Syntax Extensions][doc-syntax-extensions] +- [Installing Syntax Plug-ins][doc-plugins] + - Frontmatter + - Shortcodes + - Directives + - etc. Developer Resources -- [Conceptual Layers of glossarify-md*][doc-dev-conceptual-layers] -- [Writing Plug-ins*][doc-plugins-dev] -- [The Parsing Process and Custom Node Types*][doc-dev-node-types] + +- [Conceptual Layers of glossarify-md][doc-dev-conceptual-layers] +- [Writing Plug-ins][doc-plugins-dev] +- [The Parsing Process and Custom Node Types][doc-dev-node-types] + +Glossary + +- [Glossary][doc-glossary] (Terms and Concepts of glossarify-md) Known Issues -- [Generated Lists and Links on GitHub*][doc-lists-on-github] + +- [Generated Lists and Links on GitHub][doc-lists-on-github] diff --git a/md/doc/_pages.md b/md/doc/_pages.md new file mode 100644 index 00000000..39a10d63 --- /dev/null +++ b/md/doc/_pages.md @@ -0,0 +1,15 @@ +#### Configuration + + +#### glossarify-md + + + +#### README.md + + +#### Table of Contents + diff --git a/md/doc/_references.md b/md/doc/_references.md index c43658f8..d0d0ecd1 100644 --- a/md/doc/_references.md +++ b/md/doc/_references.md @@ -22,6 +22,11 @@ The Dublin Core Metadata Initiative. --> GitHub Flavoured Markdown +## GitHub Pages + + +GitHub Pages is a static website rendering and publishing service by GitHub Inc. + ## github-slugger A library providing support for slugs. See github-slugger. @@ -30,10 +35,6 @@ A library providing support for slugs. See github-slugger. A file pattern matcher. See glob. -## glossarify-md - -This project. - ## Hugo A static website renderer compiling an HTML website from Markdown files. @@ -72,13 +73,16 @@ See Linked Data. Specification and Implementation of a Markdown Abstract Syntax Tree. +## mdast-util-visit + + ## micromark A low-level extensible implementation of the CommonMark syntax specification (parsing and tokenizing). ## NodeJS - @@ -112,11 +116,29 @@ Generates diagrams from text files written in the PlantUML syntax. A remark syntax plug-in supporting pseudo-standard front-matter syntax. +## remark-gfm + + +A remark syntax plug-in supporting GitHub Flavoured Markdown. + +## remark plug-ins + +A curated list of remark plug-ins. + ## remark-shortcodes A remark syntax plug-in supporting non-standard Hugo shortcodes syntax. +## Semantic HTML Tags + + ## SKOS @@ -125,7 +147,7 @@ With the Simple Knowledge Organization System (SKOS) the World Wide Web Consorti ## unified -*unified* is an umbrella project around *text file processing in general*. See also [Conceptual Layers of glossarify-md](./conceptual-layers.md) +*unified* is an umbrella project around *text file processing in general*. See also Conceptual Layers of glossarify-md. ## URN @@ -146,3 +168,8 @@ A static website generator translating markdown files into a website powered by A Single Page Application framework written in JavaScript. + +## verdaccio + + +An easy to install local or on-premises npm registry. diff --git a/md/doc/cli.md b/md/doc/cli.md index 5b6310fc..05cfa46e 100644 --- a/md/doc/cli.md +++ b/md/doc/cli.md @@ -1,26 +1,37 @@ # Command Line Interface + -Get a list of command line arguments by passing `--help`. +## `--help` -## Shortcuts +Get a complete list of available command line arguments. -If you have installed glossarify-md locally to a project folder with a `package.json` then you can define an `npm run` script in the `scripts` section of your `package.json`: +## `--config [file]` -*package.json* -~~~json -{ - "scripts": { - "glossarify": "glossarify-md --config ./glossarify-md.conf.json" - } -} -~~~ -Next time you can run glossarify-md by just typing line 1. Pass arguments after a ` -- ` separator (line 2). +~~~ +npx glossarify-md --config ./glossarify-md.conf.json +~~~ -``` -1 | npm run glossarify -2 | npm run glossarify -- --help -``` +> **Tipp:** If you have installed glossarify-md locally to a project folder with a `package.json` then you can define an `npm run` script in the `scripts` section of your `package.json`: +> +>*package.json* +>~~~json +>{ +> "scripts": { +> "glossarify": "glossarify-md --config ./glossarify-md.conf.json" +> } +>} +>~~~ +> +> Next time you can run glossarify-md by just typing line 1. Pass arguments after a ` -- ` separator (line 2). +> +> ``` +> 1 | npm run glossarify +> 2 | npm run glossarify -- --help +> ``` +> ## Configuration Overrides @@ -54,3 +65,7 @@ glossarify-md --config ./glossarify-md.conf.json --deep "{'glossaries': [{'file':'./extend.md'}] }" ~~~ + +## `--watch` + +Watches `baseDir` for changes. \ No newline at end of file diff --git a/md/doc/conceptual-layers.md b/md/doc/conceptual-layers.md index c26ce2e7..cb049489 100644 --- a/md/doc/conceptual-layers.md +++ b/md/doc/conceptual-layers.md @@ -1,9 +1,7 @@ # Internals: Conceptual Layers - -[doc-syntax-extensions]: ./markdown-syntax-extensions.md -[remark-gfm]: https://npmjs.com/package/remark-gfm -[remark-plugins]: https://github.com/remarkjs/awesome-remark - + Conceptual layers of text processing by glossarify-md and projects contributing to each layer | Layer | Project | Conceptual purpose | @@ -17,4 +15,4 @@ Conceptual layers of text processing by glossarify-md and projects contributing glossarify-md is built on unified, an umbrella project for *text file processing in general*. We use unified with remark which in conceptual terms of unified is a *processor* for *Markdown text files in particular*. remark itself is built on (or better *wrapping around*) micromark which is a low-level parser/tokenizer operating on a stream of individual character symbols which drive a token state machine. micromark can be considered a technical implementation of the textual CommonMark specification. -When looking for non-standard [syntax extensions][doc-syntax-extensions] you should be looking for [remark plug-ins][remark-plugins]. Those plug-ins are likely to depend on and transitively install their preferred or required micromark extension themselves. Others may operate on layer 2 using a simpler RegEx parsing. One plug-in glossarify-md already installs itself is [remark-gfm] which adds support for the popular CommonMark syntax extension GitHub Flavoured Markdown (tables, footnotes and more). +When looking for non-standard Markdown syntax extensions you should be looking for remark plug-ins. Those plug-ins are likely to depend on and transitively install their preferred or required micromark extension themselves. Others may operate on layer 2 using a simpler RegEx parsing. One plug-in glossarify-md already installs itself is remark-gfm which adds support for the popular CommonMark syntax extension GitHub Flavoured Markdown (tables, footnotes and more). diff --git a/md/doc/cross-linking.md b/md/doc/cross-linking.md new file mode 100644 index 00000000..4b7ef339 --- /dev/null +++ b/md/doc/cross-linking.md @@ -0,0 +1,139 @@ +# Cross-Linking + +[pandoc-heading-ids]: https://pandoc.org/MANUAL.html#heading-identifiers + +> **ⓘ Since: v5.0.0** + +## Term-Based Auto-Linking + +Term-based auto-linking is to assume headings in markdown files called *glossaries* are *terms*. Whenever being mentioned in text the terms are turned into a link to the glossary section where they have been defined. **Since v5.0.0** we have evolved that principle into a more generic means of cross-linking by supporting glob patterns in `glossaries.file`. + +**Example:** + +~~~json +{ + "glossaries": [ + { "file": "./**/*.md" } + ] +} +~~~ + +Such a configuration makes glossarify-md consider every `*.md` file a *glossary* and each of its section headings *terms*. Mentioning headings (or their aliases) somewhere in the file turns the phrases into links to that section. You might want to have a look at `linking.*` config options or [Tree-scoped Linking](#tree-scoped-linking) for ways to fine-tune linkification. + +> **ⓘ** When `glossaries:[]` has multiple `file` entries, each with a glob pattern and the file sets covered by those patterns overlap, then for a file that would be come part of both file sets (intersection) only the entry *latest* in the array applies. + + + + + +## Identifier-based Cross-Linking + +When there are two or more term definitions or book sections with the same heading phrase, then you might want to refer to a particular term definition or section, in particular. While we would recommend trying [Term-based Auto-Linking](#term-based-auto-linking) with distinguished *aliases*, first, there might be situations where you might want to be explicit about a link target. glossarify-md supports [pandoc's concept of heading identifiers][pandoc-heading-ids] for identifier-based cross linking. + +> **ⓘ Note:** Pandoc's identifier syntax is not standardized in [CommonMark]. + +**Example: Identifier-based Cross-Linking** + +*./page1.md* +~~~md +## User Story {#s-241} +~~~ + +The document declares a heading-id `#s-241`. Given `#s-241` is ***unique* across all documents** then you can use it as a link reference in any file being processed... + +~~~md +[any phrase](#s-241) +~~~ + +...and glossarify-md will resolve the actual path to the corresponding section heading for you (relative or absolute based on the `paths` config option): + + +*./pages/page2.md* +~~~ +[any phrase](../page1.md#s-241) +~~~ + +## Tree-Scoped Linking + +When using term-based auto linking then, occassionally, you might find term occurrences being linkified in contexts where a link to the respective link target doesn't seem right or even a bit misleading. A manual approach to prevent this in a case-by-case decision is to wrap a term into some HTML-like tag, e.g. `term`. *Tree-scoped Linking* uses config option `linking.limitByTermOrigin` to limit the applicable scope of a term definition to a subtree of a file tree and prevent links to other parts of the tree: + +**Example: Tree-Scoped Linking** + +*Project directory layout:* +~~~ +${ROOT} + |-context-1/ + | |-context-1-1/ + | | |-document.md + | | '-glossary.md + | |-context-1-2/ + | | |-document.md + | | '-glossary.md + | '-glossary.md + | + |-context-2/ + |- ... + '-glossary.md +~~~ + +*Configuration* +~~~json +{ + "glossaries": [ + {"file": "./**/*.md" } + ], + "linking": { + "limitByTermOrigin": ["parent", "sibling", "self"] + } +} +~~~ + +A term's origin is the glossary section where the term was defined. A link is a directed edge of kind `(term-occurrence) -> (term-origin)`. So... + + +~~~json +"limitByTermOrigin": ["parent", "sibling", "self"] +~~~ + +...linkifies term occurrences when the term origin is found to be in the same file, a sibling file in same directory or a file in a direct parent directory (bottom up linking). Given above example, then + + - it *does* link term occurrences with term definitions in the same file + - it *does* link term occurrences in `context-1-1` with terms defined in `context-1` or context root `/` + - it *does not* link term occurrences in context root `/` or `context-1` with terms defined in `context-1-1` + - it *does not* link term occurrences in `context-1-1` with terms defined in `context-1-2` or `context-2` + +...and so forth, + +~~~json +"limitByTermOrigin": ["children", "sibling", "self"] +~~~ +...linkifies term occurrences only when the term was defined in the same file a file in the same directory or a file in a subdirectory (top down linking), + +~~~json +"limitByTermOrigin": ["parent", "children", "sibling", "self"] +~~~ + +...linkifies term occurrences in both directions along a filesystem path. Yet, it does not create links between branches of the file tree, e.g. it does not link terms defined in `context-1-2` with term occurrences found in `context-1-1` and vice versa, + +~~~json +limitByTermOrigin: ["parent", "children", "sibling", "parent-sibling", "self"] +~~~ + +...linkifies any term definitions with any term occurrences, including linking accross tree branches (bidirectionally). This is basically the "unlimited" default so is equivalent to `limitByTermOrigin: []`. diff --git a/md/doc/export.md b/md/doc/export.md new file mode 100644 index 00000000..88d727ce --- /dev/null +++ b/md/doc/export.md @@ -0,0 +1,45 @@ +# Export + +**Since v6.0.0** + +Exporting makes glossarify-md generate and write a structured representation of a markdown glossary to the output directory. + +## JSON (SKOS RDF/JSON-LD) + +*Example: Export terms in glossary.md as ./glossary.json* + +~~~json +{ + "glossaries": [{ + "uri": "http://basic.org/vocabulary/#", + "file": "./glossary.md", + "export": { + "file": "./glossary.json" + } + }] +} +~~~ + +> **ⓘ** We recommend declaring a glossary `uri` when exporting. It will make glossarify-md assign each term a unique *uniform resource identifier* by combining the URI with a term's term identifier. +> +> More on the idea behind URIs read Vocabulary URIs. See config option `headingIdAlgorithm` to select an algorithm for generating term identifiers from the term itself. Use pandoc syntax `{#my-own-id}` in a term heading to specify your own term identifier. + +## RDF/N-Quads + +With jsonld installed alongside glossarify-md terms can also be exported to RDF N-Quads (file extension `.nq`). + +*Example: Export terms in glossary.md as ./glossary.nq* + +~~~json +{ + "glossaries": [{ + "uri": "http://basic.org/vocabulary/#", + "file": "./glossary.md", + "export": { + "file": "./glossary.nq" + } + }] +} +~~~ \ No newline at end of file diff --git a/md/doc/gen-book-index.md b/md/doc/gen-book-index.md new file mode 100644 index 00000000..9baf0de0 --- /dev/null +++ b/md/doc/gen-book-index.md @@ -0,0 +1,42 @@ +## Generating Files: Book Index + +[doc-lists]: ./gen-lists.md + +*glossarify-md.conf.json* + +```json +"generateFiles": { + "indexFile": { + "file": "./book-index.md", + "title": "Book Index" + } +} +``` + +This option will generate a single book index file `./book-index.md` with glossary terms and links to book sections in which they have been mentioned. By default items will be grouped *by section of occurrence* using the section heading as a group title. You can disable or affect granularity of section-based grouping using: + +```json +"indexing": { + "groupByHeadingDepth": 0 +} +``` + +> **ⓘ Note**: The `groupByHeadingDepth` option also affects grouping of list items in [Lists][doc-lists]. + +Let's assume you have multiple glossaries and you want to create separate book indexes from terms of those glossaries. **Since v5.1.0** you can use `indexFiles` (plural) like this: + +```json +"generateFiles": { + "indexFiles": [{ + "title": "Book Index for Glossary 1", + "file": "./book-index-1.md", + "glossary": "./glossary-1.md" + },{ + "title": "Book Index for Glossary 2", + "file": "./book-index-2.md", + "glossary": "./glossary-2.md" + }] +} +``` + +> **ⓘ Note:** If you plan on translating markdown to HTML, e.g. with [vuepress](https://vuepress.vuejs.org), be aware that a file `index.md` will translate to `index.html` which is typically reserved for the default HTML file served under a domain. We recommend you choosing another name. diff --git a/md/doc/gen-lists.md b/md/doc/gen-lists.md new file mode 100644 index 00000000..765aed05 --- /dev/null +++ b/md/doc/gen-lists.md @@ -0,0 +1,257 @@ +### Generating Files: Lists + +[CommonMark]: https://commonmark.org +[GFM]: https://github.github.com/gfm/ + +You can generate **arbitrary lists from HTML elements with an `id` attribute** and an element *classifier* to compile similar elements into the same list. + + +*Example: Markdown document with a video element* +```md +More details see our video tutorial: + + +``` +Then to generate a *List of Videos* from all elements of `class="video"` add to your *glossarify-md.conf.json*: + +```json +"generateFiles": { + "listOf": [{ + "class": "video", + "title": "List of Videos", + "file": "./videos.md" + }] +} +``` + +After running glossarify-md there will be a file: + +*docs-glossarified/videos.md (generated)* +> ## List of Videos +> +> - [Tutorial Part 1](#video-tutorial-part-1) + +You can **type less** when prefixing ids with your list classifier: + +~~~md + +~~~ + +Without a `title` attribute the tool attempts to derive a list item label from an elements inner text content: + +~~~md + +~~~ + +Use *invisible* HTML anchors to generate lists from and navigate to text content: + +~~~md + +This is not a video tutorial but a textual tutorial. The body of text can be navigated to from a List of Tutorials and uses the classifier *tutorial*. +~~~ + +> **ⓘ Note:** If you find the browser not scrolling correctly when navigating lists on GitHub, please read [Known Issues: Lists in GitHub Repos](https://github.com/about-code/glossarify-md/blob/master/doc/lists-on-github.md). + + + +### List of Figures + +In the previous section we used [`listOf`](#generating-files-lists) to generate a list *from HTML elements* inside Markdown. Writing HTML can be annoying, particularly if there is handier Markdown syntax for the elements to be listed. This is where `listOfFigures` and [`listOfTables`](#list-of-tables) fit in. It is a shortcut which makes glossarify-md generate the HTML anchor itself from Markdown's image syntax: + +```md +![List item Label](./figure.png) +``` + +Then you may only need to use HTML for dynamically rendered figures, e.g. a PlantUML diagram: + +````md +
Dynamically Rendered Diagram
+ +```plantuml +@startuml +... your PlantUML diagram code ... +@enduml +``` +```` + +To compile both figures into the same list one way to configure glossarify-md is to declare a `listOf` class *figure* (for HTML elements) and tell `listOfFigures` (for `![]()` images) to use the same classifier *figure*: + +*glossarify-md.conf.json* (since v5.0.0) + +```json +"generateFiles": { + "listOf": [{ + "class": "figure", + "title": "List of Figures", + "file": "./figures.md" + }], + "listOfFigures": { + "class": "figure" + } +} +``` + +This configuration which would allow you to also choose a shorter classifier like *fig* is the default, though. Therefore, if you are fine with ***figure* as the default classifier** you can omit `listOf` and just use: + +*glossarify-md.conf.json* + +```json +"generateFiles": { + "listOfFigures": { + "title": "List of Figures", + "file": "./figures.md" + } +} +``` + +### List of Tables + +`listOfTables` like [`listOfFigures`](#list-of-figures) is a shortcut alternative to HTML anchors with a default [`listOf`](#lists) classifier ***table***: + +*glossarify-md.conf.json* + +```json +"generateFiles": { + "listOfTables": { + "title": "Tables", + "file": "./tables.md" + } +} +``` + +In contrast to images Markdown tables have no notion of a table caption. To render a list item for a table glossarify-md tries to infer a list item label. + +One such inference looks at the **paragraph preceding the table**. If it **ends with an *emphasized* phrase** and the phrase itself is **terminated by a colon** then the tool uses that phrase as the item label: + + + +```md +[...] which we can see from the *table of average prices by article category:* + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +But the phrase could also be it's own distinct paragraph: + + +```md +[...] which we can see from the average price by article category. + +*Average prices by category:* + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +**Since v3.4.0** there has also been support for *invisble* table captions using *HTML comment syntax*: + + +```md + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +The result for the tables above will be: + +> ## List of Tables +> +> - [Table of average prices by article category](#table-of-average-prices-by-article-category) +> - [Average prices by category](#average-prices-by-category) +> - [Average Prices by Article Category](#avg-prices) + + +**Since v5.0.0** and the introduction of [`listOf`](#generating-files-lists) all the previous examples will make glossarify-md annotate the table with an HTML anchor. While not recommended due to verbosity, you could also just add an HTML anchor yourself, of course, applying what was described in [`listOf`](#generating-files-lists) above: + +```md + + +| Category | Description | Price Avg. | +| -------- | ----------- | ---------- | +| 1 | Video Game | $35.66 | +| 2 | Film | $10.13 | +| 3 | Book | $23.45 | +``` + +> **ⓘ Note:** If glossarify-md can't find a list item label by any of the above means it will fall back to rendering a list item +> 1. using the table headers separated by comma, +> 1. or if no headers, using the closest section heading +> 1. or if no section heading, using the file name. + + + +### Lists from Regular Expressions (Experts) + +**Since v5.2.0** you can use `listOf` with a regular expression pattern. Like [`listOfFigures`](#list-of-figures) and [`listOfTables`](#list-of-tables) it is meant to be a shortcut to save you from annotating Markdown with HTML elements yourself. If the regular expression (RegExp) matches text in a paragraph, then *the paragraph* will become annotated with an HTML anchor `` preparing it for evaluation by `listOf` as we have seen above. + +**Example:** Let's assume you are writing a book with *tasks* to be accomplished by your readers. You would like to compile a *List of Tasks* in that book. You decided to use a conventional pattern which prefixes tasks with a phrase **Task:** and ends them with an exclamation mark *!* + +*Document.md* +~~~md +Some text [...] + +**Task:** Clap your hands! +~~~ + +Then you can generate a *List of Tasks* with a configuration like this: +~~~md +{ + "generateFiles": { + "listOf": [ + { + "class": "task", + "title": "Tasks in this Book", + "file": "./list-of-tasks.md", + "pattern": "Task: ([a-zA-Z0-9].*)!" + } + ] + } +} +~~~ + +Our expression uses a Capture Group in brackets `()`. Text matching the capture group pattern will become the list item label, so *Clap your hands* will become the item label, because `Task:` and exclamation mark `!` are not part of the group. There can be at most one capture group. + +> **ⓘ When to consider "Markdown" syntax in the RegExp pattern?**: +> +> You may noticed that the RegExp pattern above doesn't assume *Task:* to be written between "bold" star markers `**`, even though, that's the case in the input file *Document.md*. The pattern will be matched against *plain text* that was separated from syntactic tokens of [CommonMark] and [GFM] syntax. Other *non-standard* markdown syntax may require a special syntax plug-in which parses its tokens into an abstract syntax tree. Otherwise they will be considered plain text, too, thus have to be considered in the RegExp pattern. Unfortunately, remark plug-ins behave differently in this regard. There are plug-ins which promote special syntax which fits *their* purpose, yet *without* correctly parsing their syntax into an abstract syntax tree. So if this feature causes you headaches better try both ways or consider it not fit for your purpose. +> + +See also page Plug-ins. diff --git a/md/doc/glossary.md b/md/doc/glossary.md index 65c480ed..6ede8157 100644 --- a/md/doc/glossary.md +++ b/md/doc/glossary.md @@ -1,8 +1,6 @@ -# Glossary +# Glossary (Terms and Concepts of glossarify-md) -[glossarify-md]: https://github.com/about-code/glossarify-md - -This is a glossary of terms helpful when working with [glossarify-md] or reading its docs. It also serves as an example and is processed by *glossarify-md* itself using the [glossarify-md.conf.json](../glossarify-md.conf.json) configuration at the root of this repo. +This is a glossary of terms helpful when working with glossarify-md or reading its docs. It also serves as an example and is processed by glossarify-md itself using the [glossarify-md.conf.json](../glossarify-md.conf.json) configuration at the root of this repo. ## Alias @@ -10,7 +8,7 @@ An alternative term or spelling for a term. ## Term -A term is denoted by a heading in a markdown file which is told glossarify-md to be a *glossary file*. +Terms are headings in a markdown file which has been configured to be a *glossary file*. ## Term Attribute diff --git a/md/doc/import.md b/md/doc/import.md new file mode 100644 index 00000000..9124b8c7 --- /dev/null +++ b/md/doc/import.md @@ -0,0 +1,118 @@ +# Importing Terms + +[strip-markdown]: https://npmjs.com/package/strip-markdown + +> **⚠ Important:** glossarify-md is able to import terms and definitions from a remote location using `https`. It will try to remove any Markdown and HTML from imported data using [strip-markdown](https://npmjs.com/package/strip-markdown). Nevertheless, as a rule of thumb, **never import from untrusted sources**. +>
+> Loading files from a remote location could enable a remote entity to embed malicious code, execute such code in the runtime context of glossarify-md or make glossarify-md embed it into your output files. Consider downloading files first and after review import them statically from within your project. +
+ +---- + +### From CSV + +**Since v6.4.0** + +CSV is a textual serialization for tabular data and supported by most spreadsheed programmes. Columns in CSV are separated by a `delimiter`. + +*Example: CSV formatted tabular data delimited by `;` and without a header row* +~~~csv +#123;IGNORED-COLUMN;My Term;Alternative Term;This Term stands for Foo +~~~ + +Without a header row embedded into the CSV data a `schema` mapping is required to tell glossarify-md where to find glossary columns (resp. `fields`): + +~~~json +{ + "...": "..." + "glossaries": [{ + "uri": "http://your-domain.com/vocab/#", + "file": "./glossary.md", + "import": { + "file": "./terms.csv", + "dialect": { + "delimiter": ";", + "doubleQuotes": true + }, + "schema": { + "fields": [ + { "name": "@id"}, + { "name": "" }, + { "name": "http://www.w3.org/2004/02/skos/core#prefLabel" }, + { "name": "http://www.w3.org/2004/02/skos/core#altLabel" }, + { "name": "http://www.w3.org/2004/02/skos/core#definition" } + ] + } + }] +} +~~~ + +- Use `@id` for the ID column +- Use http://www.w3.org/2004/02/skos/core#prefLabel for the term column +- Use http://www.w3.org/2004/02/skos/core#altLabel for one or more alternative term columns (aliases) +- Use http://www.w3.org/2004/02/skos/core#definition for the term definition column + +A `schema` mapping can be omitted when the CSV file embeds these as header labels in the first row: + +*Example: CSV with a header row* +~~~csv +@id;http://www.w3.org/2004/02/skos/core#prefLabel;http://www.w3.org/2004/02/skos/core#altLabel;http://www.w3.org/2004/02/skos/core#definition + +#123;My Term;Alternative Term;This Term stands for Foo +~~~ + +### From JSON (glossarify-md exports) + +**Since v6.0.0** + +~~~json +{ + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./terms.json" + } + }] +} +~~~ + +### From JSON (arbitrary) + +~~~json +{ + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./terms.json", + "context": "./mapping.jsonld" + } + }] +} +~~~ + +Importing from arbitrary data models and JSON serializations is likely to require mappings onto SKOS types and attributes. See Interoperability with SKOS and JSON-LD for an in-depth example. + +### From RDF + SKOS + +**Since v6.0.0** + +If you have an SKOS description of a glossary or taxonomy stored in some RDF linked data store then you might find linked data tooling that is able to export/convert/serialize your linked data vocabulary to **N-Triples, N-Quads or JSON-LD**. + +- Importing from JSON-LD should work similar to importing glossarify-md's own JSON exports +- Importing N-Triples/N-Quads requires the file name to end with `.nq` + +*Example: Import RDF + SKOS from an N-Quads serialization:* +~~~json +{ + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./terms.nq" + } + }] +} +~~~ + + diff --git a/md/doc/install.md b/md/doc/install.md new file mode 100644 index 00000000..a5c18919 --- /dev/null +++ b/md/doc/install.md @@ -0,0 +1,40 @@ +# Install + +### Option 1: Install *locally*, init, configure, run: + +~~~ +cd ./your-project +npm install glossarify-md + +npx glossarify-md --init --new --local +npx glossarify-md --config ./glossarify-md.conf.json +~~~ + +When installing locally you might want to set up a shortcut by adding a run script to your `package.json`: + +~~~json +{ + "scripts": { + "glossarify": "glossarify-md --config ./glossarify-md.conf.json" + } +} +~~~ + +Now use: + +~~~ +npm run glossarify +~~~ + +### Option 2: Install *globally*, init, configure, run: + +~~~ +npm install -g glossarify-md + +glossarify-md --init --new +glossarify-md --config ./glossarify-md.conf.json +~~~ + +> **ⓘ** Many editors and IDEs use a `$schema` configuration schema declaration to provide you with assistance in editing a JSON config file. Installing glossarify-md globally will require `$schema` to point to a configuration schema hosted on GitHub. That schema refers to the version that has been used when the configuration file was created, initially. Later, when updating the global installation of glossarify-md pointers in your project configurations won't be updated and continue to point the config schema version at initialization time. This is not an issue at all. Just note that editors won't suggest newer options from the latest globally installed release unless you update the `$schema` url to match the config schema version that is in line with the current install. However you'll receive a command line hint when glossarify-md detects such a situation. + +See also page Configuration. \ No newline at end of file diff --git a/md/doc/lists-on-github.md b/md/doc/lists-on-github.md index ed857499..05387fb5 100644 --- a/md/doc/lists-on-github.md +++ b/md/doc/lists-on-github.md @@ -1,31 +1,46 @@ # Known Issues: Lists in GitHub Repos + +[2]: <#large-file-link-target> -[doc-readme-lists]: ../README.md#lists -[gfm-sanitize]: https://github.github.com/gfm/#what-is-github-flavored-markdown- -[gh-pages]: https://pages.github.com/ -[html-sem-tags]: https://www.w3schools.com/html/html5_semantic_elements -[2]: <> +**Note:** This issue may only affect you or your readers -Addendum to [Section *Lists* in README.md][doc-readme-lists] +1. when navigating GitHub *previews* of Markdown files within a GitHub repository +2. when navigating from a list item generated with the `listOf` config option to a link target that requires the browser to scroll the link target into the visible viewport -We assume you have generated a `list.md` file using a `listOf` config: +The issue is: *the browser may not scroll the link target into the visible viewport as expected. -> ## [My List](#my-list) -> -> * [List item title][2] +## Reproduction of the Issue -The list item was generated from a document with an element +Let's imagine such a GitHub repository. It has a file `README.md` that has a lot of text and some addressable HTML element `` quite at the bottom of that page: -```md -... lot's of text here... -List item title -``` + *README.md* -where `cite` is at the bottom of a larger file `page.md` and, initially, *out of the visible viewport* of a browser. -Normally, when converting such markdown to HTML using a Markdown-to-HTML static page renderer you would expect the list item link to be a link which targets the document *but also* make the browser scroll to make the targeted section part of the visible viewport. + ~~~md + ... lot's of text here... + Some Magazine Title + ~~~ -On a GitHub repository, though, you'll find that you can navigate within the repository using the list item link in `list.md` but the browser *won't* scroll to the item position `#mylist-foo` in `page.md`. The reason for this is that GitHub *[sanitizes][gfm-sanitize]* Markdown files before rendering them within their own repository previews. They allow only a small subset of HTML and strip elements like `` and other [Semantic HTML Tags][html-sem-tags] including the element's `id="#mylist-foo"` which a browser needs to be able to scroll to that part of an HTML document. Therefore, if you care for navigability in GitHub repositories, just use supported elements like `` or `` instead. +- ...to have a file `list.md` generated using `listOf` with `class: "citations"`: -**This is a limitation of GitHub's repository preview renderer *only*!** It is not a bug in glossarify-md. For example, if you were rendering `list.md` and `page.md` with a static website generator like Jekyll or vuepress things work just fine. + *list.md* + ~~~md + ## [Citations](#my-list) -You can even try yourself with [GitHub Pages][gh-pages] which renders `.md` files in a repo to https://yoursite.github.io using Jekyll. + * [Some Magazine Title][2] + + [2]: ./README.md#some-magazine + ~~~ + +Then you browse the repository in the web browser enjoying GitHubs preview of Markdown files in the repo. You would like to navigate from `list.md` to `./README.md#some-magazine` by clicking the list item link generated by glossarify-md. You'd expect your browser to *scroll* to the link target quite at the bottom of `page.md` *but it doesn't!* + +## Root Cause + +**GitHub sanitizes Markdown files** (see GFM Sect.1.1) before HTML-rendering them within repository previews. It does so to safeguard GitHub users from evil repository owners who attempt to embed scripts and harmful content into markdown and make that content execute in a victims browser while it browses GitHub. To prevent that GitHub only allows for a small subset of the most commonly used and safe HTML tags and strips others. `` is among those that *are* stripped. The browser therefore can't find that element in the Markdown preview and consequently can't scroll to it. + +## Workaround + +If you care for navigability in GitHub repositories only use HTML tags like `` or `` that aren't stripped in GitHub repository previews. + +**Note that this is a limitation of GitHub's repository preview renderer *only*!** It is not a bug in glossarify-md and once you use a static website generator to generate HTML files from Markdown in order to host them on GitHub Pages or your own webserver, things will work just fine. It's just when navigating GitHub *previews* of Markdown files where things may not work as you would expect them to do. \ No newline at end of file diff --git a/md/doc/markdown-syntax-extensions.md b/md/doc/markdown-syntax-extensions.md index f7961142..19520383 100644 --- a/md/doc/markdown-syntax-extensions.md +++ b/md/doc/markdown-syntax-extensions.md @@ -1,12 +1,7 @@ # Markdown Syntax Extensions - -[doc-conceptual-layers]: ./conceptual-layers.md -[doc-plugins]: ./plugins.md -[doc-plugins-dev]: ./plugins-dev.md -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter -[remark-plugins]: https://github.com/remarkjs/awesome-remark -[unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md - + glossarify-md supports CommonMark and GitHub Flavoured Markdown (GFM). Syntax not covered by these specifications may have no or worse, a wrong representation in the tool's Abstract Syntax Tree (mdAst). As a consequence it may not make it correctly into output documents. For example *Frontmatter* syntax is a Markdown syntax extension popularized by many static site generators: *Frontmatter Syntax* @@ -19,4 +14,4 @@ key: This is a frontmatter Without special support for it CommonMark compliant parsers like our remark parser will interpret the line of trailing dashes as *heading* markers and the text before them as *heading text*. So to make our parser aware of frontmatter syntax we need to enhance it. -**Since v5.0.0** we have opened glossarify-md to the [remark plug-in ecosystem][remark-plugins] and its support of additional syntaxes and tools. More see [Installing Plug-ins][doc-plugins] and [Writing a Plug-in][doc-plugins-dev]. +**Since v5.0.0** we have opened glossarify-md to the remark plug-in ecosystem and its support of additional syntaxes and tools. More see Installing Plug-ins and Writing a Plug-in. diff --git a/md/doc/plugins-dev.md b/md/doc/plugins-dev.md index 2b3b1b5b..3a786dcb 100644 --- a/md/doc/plugins-dev.md +++ b/md/doc/plugins-dev.md @@ -1,18 +1,17 @@ # Writing a Plug-In - -[doc-conceptual-layers]: ./conceptual-layers.md -[mdast-util-visit]: https://npmjs.com/package/mdast-util-visit + [remark-discussion]: https://github.com/remarkjs/remark/discussions/869#discussioncomment-1602674 -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter -[verdaccio]: https://npmjs.com/package/verdaccio + ## Syntax Plug-Ins -Syntax Plug-ins extend Markdown syntax itself, like [remark-frontmatter], for example. They contribute new *node types* to an internal Abstract Syntax Tree (AST). Further they provide a tokenizer to parse and a serializer to write markdown files. Writing syntax plug-ins is a bit more elaborate. At this point we like to refer you to the documentation of micromark and mdAst. When exploring these projects you might find this [description of the overall process][remark-discussion] helpful. +Syntax Plug-ins extend Markdown syntax itself, like remark-frontmatter, for example. They contribute new *node types* to an internal Abstract Syntax Tree (AST). Further they provide a tokenizer to parse and a serializer to write markdown files. Writing syntax plug-ins is a bit more elaborate. At this point we like to refer you to the documentation of micromark and mdAst. When exploring these projects you might find this [description of the overall process][remark-discussion] helpful. ## Tree-Plug-Ins -*Tree plug-ins* operate on a markdown syntax tree (mdAST). They are much easier to write and use CommonMark and GFM syntax and respective AST node types to do their job. Basically they inspect, add, remove or resort AST nodes. glossarify-md operates on tree plug-ins, almost only (see [Conceptual Layers][doc-conceptual-layers]). +*Tree plug-ins* operate on a markdown syntax tree (mdAST). They are much easier to write and use CommonMark and GFM syntax and respective AST node types to do their job. Basically they inspect, add, remove or resort AST nodes. glossarify-md operates on tree plug-ins, almost only (see page Conceptual Layers). -A tree plug-in is a function which returns a callback that when called get's passed an mdAst root node (`tree`): +A tree plug-in is a function which returns a callback function. The callback function receives an mdAst node (usually the root node for a markdown file) whose subtree can be inspected and modified by visiting all or particular types of nodes: *remark-my-plug-in.js* ~~~js @@ -35,7 +34,7 @@ export default function myPlugin(options = {}) { The example simply adds a `&visited=true` URL query parameter to each Markdown link in a document. -It uses a [visit][mdast-util-visit] utility function with a filter argument (2) and visitor callback argument (3). The filter argument can be the name of a node type or a filter function which gets passed a node and is expected to return a boolean. For a list of CommonMark node types see mdAst. Eventually, the plug-in function returns the tree's root node again. +It uses a *visit* utility function (see mdast-util-visit) with a filter argument (2) and visitor callback argument (3). The filter argument can be the name of a node type or a filter function which gets passed a node and is expected to return a boolean. For a list of CommonMark node types see mdAst. Eventually, the plug-in function returns the tree's root node again. Note the `options` argument: this is how your plug-in would get passed its config options (see [Installing Plug-Ins](#installing-plug-ins)). Let's save the plug-in to *plugins/remark-my-plug-in.js* next to `outDir`: @@ -129,6 +128,6 @@ npm pack The command creates a `tar.gz` file. Inspect its contents. Optionally, use a `files` whitelist in `package.json` to select which files should go into a package. -> Prior to publishing to the official npm registry, you may also find setting up a test registry on `localhost` useful. See [verdaccio], for an example. +> Prior to publishing to the official npm registry, you may also find setting up a test registry on `localhost` useful. See verdaccio, for an example. More see official NPM docs on [publishing your node package](https://docs.npmjs.com/packages-and-modules). diff --git a/md/doc/plugins.md b/md/doc/plugins.md index c6cb233c..38c3b04f 100644 --- a/md/doc/plugins.md +++ b/md/doc/plugins.md @@ -1,16 +1,10 @@ # Installing and Configuring Plug-ins - -[doc-conceptual-layers]: ./conceptual-layers.md -[doc-plugins-dev]: ./plugins-dev.md -[doc-mdext-syntax]: ./markdown-syntax-extensions.md -[mdast-util-visit]: https://npmjs.com/package/mdast-util-visit -[remark-discussion]: https://github.com/remarkjs/remark/discussions/869#discussioncomment-1602674 -[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter -[remark-plugin]: https://github.com/remarkjs/awesome-remark + [unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md -[verdaccio]: https://npmjs.com/package/verdaccio -The following example demonstrates how to install [remark-frontmatter], a [remark plug-in][remark-plugin] to make glossarify-md handle non-standard *Frontmatter* syntax, correctly ([When do I need a plug-in?][doc-mdext-syntax]). +The following example demonstrates how to install remark-frontmatter, a syntax plug-in from the remark plug-in ecosystem which makes glossarify-md (resp. its internal remark parser) handle non-standard *Frontmatter* syntax, correctly (See Markdown Syntax Extensions for when you need a plug-in). > **ⓘ Note:** glossarify-md does not guarantee compatibility with plug-ins and likely won't help with issues arising due to installing and using additional third-party plug-ins. @@ -26,7 +20,7 @@ ${root} '- .gitignore ~~~ -**1:** Install [remark-frontmatter]: +**1:** Install remark-frontmatter: ~~~ npm install remark-frontmatter @@ -50,9 +44,9 @@ npm install remark-frontmatter Keys of the `plugins` object tell what plug-in to load and may be: - a name of an npm package in a global or local `node_modules` folder -- a path to a JavaScript file exporting a plug-in function (see [writing plug-ins][doc-plugins-dev]) +- a path to a JavaScript file exporting a plug-in function (see page Writing a Plug-in) -Their value in turn are options passed to the plug-in. Read [remark-frontmatter] docs, to find out about available options. +Their value in turn are options passed to the plug-in. Read remark-frontmatter docs, to find out about available options. > ⓘ The `unified` key embeds a [unified configuration][unified-config] object. Its schema is *not* subject to glossarify-md's own config schema, anymore. Thus, if you would like to have the configs separated a bit more clearly, then you can split them: > @@ -79,4 +73,5 @@ Their value in turn are options passed to the plug-in. Read [remark-frontmatter] > } > ``` > -> If you would like to learn more about how *unified* and *remark* relate to glossarify-md, read [Conceptual Layers][doc-conceptual-layers]. + +If you would like to learn more about how *unified* and *remark* relate to glossarify-md, read Conceptual Layers diff --git a/md/doc/references.md b/md/doc/references.md index 403b51a6..51978c91 100644 --- a/md/doc/references.md +++ b/md/doc/references.md @@ -1,32 +1,27 @@ -# Managing References +# Citations and References -In order to cite a source on the web whenever using a particular term use a glossary configuration with `linkUris: true`: +[Shannon1948]: https://doi.org/10.1002/j.1538-7305.1948.tb01338.x -*glossarify-md.conf.json* -~~~json -{ - "glossaries": [ - { - "file": "./references.md", - "linkUris": true - } - ] -} +A way to use glossarify-md for citing and linking is to have a file, e.g. `references.md` ... + +~~~md +# References + +## Shannon1948 + + +C. E. Shannon, "A mathematical theory of communication," in The Bell System Technical Journal, vol. 27, no. 3, pp. 379-423, July 1948, doi: 10.1002/j.1538-7305.1948.tb01338.x. ~~~ -Within file `./references.md` use the term attribute `uri` to provide the source's URL. Optionally you can add an `aliases` term attribute to make further terms refer to a particular source and provide a tooltip for the link. +...and configure it as a glossary: -*references.md* -~~~md -## CommonMark - - -## Dublin Core - -The Dublin Core Metadata Initiative. +~~~json +{ + "glossaries": [{ + "file": "./references.md", + "linkUris": true + }] +} ~~~ -See an example by inspecting the markdown source of [_references.md](./_references.md) or this repository's [glossarify-md.conf.json](../glossarify-md.conf.json). +Use `linkUris: true` to make glossarify-md link occurrences of [Shannon1948] to the web using its `uri`. With `linkUris: false` (default) it links to `references.md`. diff --git a/md/doc/skos-interop.md b/md/doc/skos-interop.md index 384ebdb3..799effc3 100644 --- a/md/doc/skos-interop.md +++ b/md/doc/skos-interop.md @@ -1,12 +1,11 @@ # Interoperability with SKOS and JSON-LD - -[doc-export-import]: ../README.md#structured-export-and-import + > Readers Level: *Advanced* > > The term *term* can become itself confusing in this section. Therefore we'll say *model terms* if we refer to a vocabulary of technical attribute names or type names of a data model. We'll say *glossary terms* if we refer to the actual terms of a glossary (an instance of that data model). -**Since v6.0.0** glossarify-md supports [exporting and importing][doc-export-import] glossaries. In addition to importing terms from files exported by glossarify-md itself it can import glossary terms from arbitrarily structured JSON documents once there are mappings of the other document's *model terms* onto "well-known" SKOS and Dublin Core model terms. +**Since v6.0.0** glossarify-md supports exporting and importing glossaries. In addition to importing terms from files exported by glossarify-md itself it can import glossary terms from arbitrarily structured JSON documents once there are mappings of the other document's *model terms* onto "well-known" SKOS and Dublin Core model terms. Model terms understood by glossarify-md are: diff --git a/md/doc/term-attributes.md b/md/doc/term-attributes.md index cd115f3f..b5790da8 100644 --- a/md/doc/term-attributes.md +++ b/md/doc/term-attributes.md @@ -1,39 +1,35 @@ # Term Attributes -[doc-aliases]: ../README.md#aliases-and-synonyms -[doc-vocabularies]: ./vocabulary-uris.md +Term Attributes provide additional metadata for a term. They are passed in a comment following a term heading: -Term Attributes are passed in a comment following a term's heading. The comment text must adhere to YAML syntax. - -**Since v6.3.0** glossarify-md supports YAML syntax. Its easy to learn and a natural fit with Markdown. For example, this will be all you need to understand and use term attributes: - -*my-glossary.md* ~~~md # Term Heading - -... + +Term definition here. ~~~ -> **ⓘ Note:** YAML syntax is *case-sensitive* and like Markdown it is *sensitive to tabs and whitespaces*. In general term attributes will be lowercase. +**Since v6.3.0** term attributes use YAML syntax. The example shows two term attributes `key1` and `key2` where `key2` has multiple attribute values. + +> **ⓘ Note:** YAML syntax is *case-sensitive* and *sensitive to tabs and whitespaces* (like Markdown). As a rule of thumb: our own term attributes will be all lowercase. -## Attributes +## Supported Term Attributes ### `aliases` -Comma-separated string or a string array listing alternative spellings that should be linked with a term definition when found in text. More see [README.md][doc-aliases] +Expects a comma-separated string or a list of strings which provide synonyms or alternative spellings for a term that should be linked with a term definition when found in text. More see README.md -> **ⓘ Note:** You may find that an uppercase `Aliases: ` term attribute works as well. This is going to be the only attribute for which an uppercase name remains supported *for backwards compatibility*. +> **ⓘ Note:** Uppercase `Aliases` remains to be supported for backwards compatibility. ### `uri` -An identifier for the term's *meaning*. Can be used to link term occurrences to an authoritative definition on the web instead of linking term occurrences to a markdown book's glossary. Web linking requires setting `linkUris: true` for a `glossaries` item in a glossarify-md configuration file. More see *[URIs as Identifiers for Definitions of Meaning][doc-vocabularies]* +A unique identifier for the term and the definition of it's *meaning*. Use `linkUris: true` with a `glossaries` config in a glossarify-md configuration file to link term occurrences to an authoritative definition on the web using the term's `uri` term attribute. See also *URIs as Identifiers for Definitions of Meaning*. # Addendum @@ -41,7 +37,7 @@ There's going to be continued support for JSON term attribute syntax, for backwa ~~~md # Term Heading - *Input (JSON)* ~~~md # Term - @@ -104,7 +100,7 @@ Replace: ~~~md # Term - diff --git a/md/doc/use-with-hugo.md b/md/doc/use-with-hugo.md index 084c0fd7..d81164da 100644 --- a/md/doc/use-with-hugo.md +++ b/md/doc/use-with-hugo.md @@ -1,17 +1,14 @@ # Using glossarify-md with Hugo + -[doc-linking]: https://github.com/about-code/glossarify-md/blob/master/doc/README.md#linking -[doc-plugins]: ./plugins.md -[doc-mdext-syntax]: ./markdown-syntax-extensions.md [hugo-page-bundles]: https://gohugo.io/content-management/page-bundles/ [hugo-frontmatter]: https://gohugo.io/content-management/front-matter/ [hugo-shortcodes]: https://gohugo.io/content-management/shortcodes/ [hugo-cm-compliance]: https://github.com/about-code/glossarify-md/issues/165#issuecomment-1086874898 -[known issues]: #known-issues Below we provide a few *examples* on how you *might* be able to facilitate glossarify-md in a Hugo project. But note that existence of this page is not a statement about *Hugo compatibility*. -## Setup +## Setup Hugo with glossarify-md 1. Install NodeJS and npm 1. In your Hugo project folder install glossarify-md @@ -24,7 +21,7 @@ Below we provide a few *examples* on how you *might* be able to facilitate gloss ## Install Plug-Ins -Hugo supports some Markdown syntax not [supported out-of-the-box by glossarify-md][doc-mdext-syntax]. See the table below which syntax (left column) requires [installing and configuring a plug-in][doc-plugins] (right column). See the plug-in's docs for available config options and default values. +Hugo supports some Markdown syntax extensions not supported out-of-the-box by glossarify-md. See the table below which kind of syntax (left column) requires installing and configuring a plug-in (right column). See the plug-in's docs for available config options and default values. ~~~ npm install remark-frontmatter remark-shortcodes @@ -166,13 +163,13 @@ ${root} } ~~~ -## Run +## Run glossarify-md ~~~ npx glossarify-md --config ./glossarify-md.conf.json ~~~ -You should now see the files in `content_` copied to `content` where they will be picked up by Hugo. Should you have any troubles with paths, see also [`linking` options][doc-linking]. +You should now see the files in `content_` copied to `content` where they will be picked up by Hugo. Should you have any troubles with paths, see also `linking` config option. ## Known Issues @@ -183,7 +180,7 @@ https://github.com/about-code/glossarify-md/issues/246 Hugo and glossarify-md support an overlapping, yet not identical set of Markdown syntax constructs. They share the common set of CommonMark and GFM constructs. But there is a chance Hugo supports additional features neither in Commonmark nor GFM. As a glossarify-md-with-Hugo user you may - need to restrict yourself to using the common set of syntax, only -- or need to [install a syntax plug-in][doc-plugins], when there's one available +- or need to install a syntax plug-in, when there's one available - or need to step back from glossarify-md given you can't sacrifice certain Hugo features. diff --git a/md/doc/use-with-pandoc.md b/md/doc/use-with-pandoc.md index 1c8cfb19..8c1c446f 100644 --- a/md/doc/use-with-pandoc.md +++ b/md/doc/use-with-pandoc.md @@ -1,5 +1,5 @@ # Using glossarify-md with pandoc - + ~~~ ${root} +- docs/ diff --git a/md/doc/use-with-vuepress.md b/md/doc/use-with-vuepress.md index f2478620..1f943b3c 100644 --- a/md/doc/use-with-vuepress.md +++ b/md/doc/use-with-vuepress.md @@ -1,9 +1,14 @@ # Using glossarify-md with vuepress + -Below we assume a *sample* project structure like this: +[vp-frontmatter]: https://vuepress.vuejs.org/guide/markdown.html#frontmatter +[vp-cc]: https://vuepress.vuejs.org/guide/markdown.html#custom-containers +[vp-emoji]: https://vuepress.vuejs.org/guide/markdown.html#emoji +[vp-toc]: https://vuepress.vuejs.org/guide/markdown.html#table-of-contents +[vp-lh]: https://vuepress.vuejs.org/guide/markdown.html#line-highlighting-in-code-blocks +[vp-code]: https://vuepress.vuejs.org/guide/markdown.html#import-code-snippets -[doc-syntax-extensions]: ./markdown-syntax-extensions.md -[doc-plugins]: ./plugins.md +Below we assume a *sample* project structure like this: ``` ${root} @@ -96,7 +101,7 @@ More information see [README.md](../README.md). ## Install and Configure Syntax Extension Plug-Ins -vuepress supports some [Markdown syntax](https://vuepress.vuejs.org/guide/markdown.html) not covered by CommonMark or GFM. See the table below which syntax extension on the left requires [installing and configuring a plug-in][doc-plugins] on the right. See the respective plug-in for its individual default values and config options. +vuepress supports some [Markdown syntax](https://vuepress.vuejs.org/guide/markdown.html) not covered by CommonMark or GFM. See the table below which syntax extension on the left requires installing and configuring a plug-in on the right. See the respective plug-in for its individual default values and config options. | Markdown Syntax Extension | remark plug-in required with glossarify-md | @@ -108,13 +113,6 @@ vuepress supports some [Markdown syntax](https://vuepress.vuejs.org/guide/markdo | [Line Highlighting Codeblocks][vp-lh] | - | | [Import Code Snippets][vp-code] | - | -[vp-frontmatter]: https://vuepress.vuejs.org/guide/markdown.html#frontmatter -[vp-cc]: https://vuepress.vuejs.org/guide/markdown.html#custom-containers -[vp-emoji]: https://vuepress.vuejs.org/guide/markdown.html#emoji -[vp-toc]: https://vuepress.vuejs.org/guide/markdown.html#table-of-contents -[vp-lh]: https://vuepress.vuejs.org/guide/markdown.html#line-highlighting-in-code-blocks -[vp-code]: https://vuepress.vuejs.org/guide/markdown.html#import-code-snippets - ## Appendix *Slugs* are "*URL-friendly IDs*" used to identify a content section *within* a hypermedia document. They are not required to locate the document but needed to make a browser navigate to a particular content section *within* a document, for example `https://foo.com/#my-slug` identifies a content section using the Slug or *URL fragment* `#my-slug`. diff --git a/md/doc/vocabulary-uris.md b/md/doc/vocabulary-uris.md index a1c2ba19..6d8447bb 100644 --- a/md/doc/vocabulary-uris.md +++ b/md/doc/vocabulary-uris.md @@ -1,4 +1,7 @@ # URIs as Identifiers for *Definitions of Meaning* + [headingIdAlgorithm]: ../README.md#headingidalgorithm [doc-import]: ../README.md#structured-export-and-import @@ -11,7 +14,7 @@ Consider a term *skin*. In human medicine it's a term for a human organ while in - `https://example.com/glossary/medicine/#skin` - `https://example.com/glossary/computer-science/#skin`. -a computer can operate on symbols equivalent to *some meaning* without having to know the exact meaning. Such IDs can then be used, for example, to establish relationships between semantic concepts (like `xID not-equal yID`). Semantic modeling goes beyond glossaries. Assigning glossary terms unique IDs, though, enables using them in other technical implementations of knowledge organization systems such as thesauri, taxonomies or word nets. +a computer can operate on symbols equivalent to *some meaning* without having to know the exact meaning. Such IDs can then be used, for example, to establish relationships between semantic concepts (like `xID not-equal yID`). Semantic modeling goes beyond glossaries. Assigning glossary terms unique IDs, though, enables using them in other technical implementations of knowledge organization systems such as thesauri, taxonomies or word nets. **Since v6.0.0** glossarify-md supports [exporting and importing][doc-import] glossaries (see also [Interoperability with SKOS and JSON-LD][doc-skos]). @@ -64,7 +67,7 @@ URIs can be *just identifiers*. But URIs can also be used to *locate and retriev ### Authority -URIs for terms reveal the authoritative source for a particular definition, which in our example was `example.com`. While anyone could use any domain name in an URI and make it the identifier of something (like we did in our examples) only the legitimate domain name owner as registered in the Domain Name System (DNS) can claim authority in case of disputes over some definition. +URIs for terms reveal the authoritative source for a particular definition, which in our example was `example.com`. While anyone could use any domain name in an URI and make it the identifier of something (like we did in our examples) only the legitimate domain name owner as registered in the Domain Name System (DNS) can claim authority in case of disputes over some definition. So in this particular example we could *not* veto if the owners of domain `example.com` chose to use above URIs to identify something else. By using another domain name than our own we effectively accept that there could be conflicting definitions wiping out the purpose of an URI. So particularly when publishing a vocabulary it is usually not a good idea to use someone else's domain. diff --git a/package-lock.json b/package-lock.json index 94ae7313..576b4726 100644 --- a/package-lock.json +++ b/package-lock.json @@ -10,6 +10,7 @@ "license": "MIT", "dependencies": { "chokidar": "^3.5.3", + "csv-parse": "^5.3.5", "deepmerge": "^4.2.2", "fs-extra": "^10.0.1", "github-slugger": "^1.0.0", @@ -51,6 +52,7 @@ "node": "^12.20.0 || ^14.13.1 || >=16.0.0" }, "optionalDependencies": { + "csv-parse": "^5.3.5", "jsonld": "^5.2.0" }, "peerDependencies": { @@ -1723,6 +1725,12 @@ "node": ">= 8" } }, + "node_modules/csv-parse": { + "version": "5.3.5", + "resolved": "https://registry.npmjs.org/csv-parse/-/csv-parse-5.3.5.tgz", + "integrity": "sha512-8O5KTIRtwmtD3+EVfW6BCgbwZqJbhTYsQZry12F1TP5RUp0sD9tp1UnCWic3n0mLOhzeocYaCZNYxOGSg3dmmQ==", + "optional": true + }, "node_modules/cuint": { "version": "0.2.2", "resolved": "https://registry.npmjs.org/cuint/-/cuint-0.2.2.tgz", @@ -8340,6 +8348,12 @@ "which": "^2.0.1" } }, + "csv-parse": { + "version": "5.3.5", + "resolved": "https://registry.npmjs.org/csv-parse/-/csv-parse-5.3.5.tgz", + "integrity": "sha512-8O5KTIRtwmtD3+EVfW6BCgbwZqJbhTYsQZry12F1TP5RUp0sD9tp1UnCWic3n0mLOhzeocYaCZNYxOGSg3dmmQ==", + "optional": true + }, "cuint": { "version": "0.2.2", "resolved": "https://registry.npmjs.org/cuint/-/cuint-0.2.2.tgz", diff --git a/package.json b/package.json index 45040df2..233d54d8 100644 --- a/package.json +++ b/package.json @@ -97,6 +97,7 @@ "inquirer": "^8.2.0" }, "optionalDependencies": { + "csv-parse": "^5.3.5", "jsonld": "^5.2.0" }, "remarkConfig": { diff --git a/test/input/config-glossaries/import-csv/with-columns-map-to-array/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-columns-map-to-array/glossarify-md.conf.json new file mode 100644 index 00000000..19fa0dcd --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-columns-map-to-array/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-array", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-array/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-columns-map-to-array/glossary.csv b/test/input/config-glossaries/import-csv/with-columns-map-to-array/glossary.csv new file mode 100644 index 00000000..bfafb90b --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-columns-map-to-array/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:altLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1;Alias 1.2;Alias 1.3;GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term. +#2;Imported Term 2;Alias 2.1;Alias 2.2;Alias 2.3;GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term. diff --git a/test/input/config-glossaries/import-csv/with-columns-map-to-scalar/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-columns-map-to-scalar/glossarify-md.conf.json new file mode 100644 index 00000000..b2c98a76 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-columns-map-to-scalar/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-scalar", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-scalar/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.csv b/test/input/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.csv new file mode 100644 index 00000000..aecac6df --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition;skos:definition +#1;Imported Term 1;Alias 1.1, Alias 1.2, Alias 1.3;GIVEN multiple columns of skos:definition AND skos:definition maps to a term's definition AND a term definition is a scalar property THEN the value of none or the first or the last column SHOULD become the term's definition but not both.;Definition 1.2 +#2;Imported Term 2;Alias 2.1, Alias 2.2, Alias 2.3;GIVEN multiple columns of skos:definition AND skos:definition maps to a term's definition AND a term definition is a scalar property THEN the value of none or the first or the last column SHOULD become the term's definition but not both.;Definition 2.2 diff --git a/test/input/config-glossaries/import-csv/with-columns-partly-not-skos/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-columns-partly-not-skos/glossarify-md.conf.json new file mode 100644 index 00000000..08d5c281 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-columns-partly-not-skos/glossarify-md.conf.json @@ -0,0 +1,24 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-columns-partly-not-skos", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv", + "schema": { + "fields": [ + {"name": "@id"} + ,{"name": "ignore"} + ,{"name": "ignore"} + ,{"name": "http://www.w3.org/2004/02/skos/core#prefLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#altLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#definition"} + ] + } + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-columns-partly-not-skos/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.csv b/test/input/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.csv new file mode 100644 index 00000000..38abd27a --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.csv @@ -0,0 +1,2 @@ +#1;IGNORE-1.1;IGNORE-1.2;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;IGNORE-2.1;IGNORE-2.2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/input/config-glossaries/import-csv/with-custom-delimiter/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-custom-delimiter/glossarify-md.conf.json new file mode 100644 index 00000000..daed88d3 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-custom-delimiter/glossarify-md.conf.json @@ -0,0 +1,18 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-custom-delimiter", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv", + "dialect": { + "delimiter": "|", + "doubleQuote": true + } + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-custom-delimiter/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-custom-delimiter/glossary.csv b/test/input/config-glossaries/import-csv/with-custom-delimiter/glossary.csv new file mode 100644 index 00000000..21e56214 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-custom-delimiter/glossary.csv @@ -0,0 +1,2 @@ +@id|skos:prefLabel|skos:altLabel|skos:definition +#1|Imported Term 1| Alias 1.1,Alias 1.2,Alias 1.3|GIVEN a custom separator '|' THEN columns should still be imported correctly. diff --git a/test/input/config-glossaries/import-csv/with-headers-and-prefixes/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-headers-and-prefixes/glossarify-md.conf.json new file mode 100644 index 00000000..eca28cb7 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-and-prefixes/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-prefixes", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-prefixes/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-headers-and-prefixes/glossary.csv b/test/input/config-glossaries/import-csv/with-headers-and-prefixes/glossary.csv new file mode 100644 index 00000000..7066b072 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-and-prefixes/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/input/config-glossaries/import-csv/with-headers-and-uris/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-headers-and-uris/glossarify-md.conf.json new file mode 100644 index 00000000..1e521aa5 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-and-uris/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-uris", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-uris/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-headers-and-uris/glossary.csv b/test/input/config-glossaries/import-csv/with-headers-and-uris/glossary.csv new file mode 100644 index 00000000..1196fd9b --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-and-uris/glossary.csv @@ -0,0 +1,3 @@ +@id;http://www.w3.org/2004/02/skos/core#prefLabel;http://www.w3.org/2004/02/skos/core#altLabel;http://www.w3.org/2004/02/skos/core#definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced. diff --git a/test/input/config-glossaries/import-csv/with-headers-configured/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-headers-configured/glossarify-md.conf.json new file mode 100644 index 00000000..2b8fcefe --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-configured/glossarify-md.conf.json @@ -0,0 +1,26 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-configured", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + ,"dialect": { + "delimiter": ";", + "doubleQuote": true + } + ,"schema": { + "fields": [ + {"name": "@id"} + ,{"name": "http://www.w3.org/2004/02/skos/core#prefLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#altLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#definition"} + ] + } + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-configured/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-headers-configured/glossary.csv b/test/input/config-glossaries/import-csv/with-headers-configured/glossary.csv new file mode 100644 index 00000000..b76e0949 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-configured/glossary.csv @@ -0,0 +1,2 @@ +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/input/config-glossaries/import-csv/with-headers-missing/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-headers-missing/glossarify-md.conf.json new file mode 100644 index 00000000..fb5d1a46 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-missing/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-missing", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-missing/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-headers-missing/glossary.csv b/test/input/config-glossaries/import-csv/with-headers-missing/glossary.csv new file mode 100644 index 00000000..b76e0949 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-headers-missing/glossary.csv @@ -0,0 +1,2 @@ +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossarify-md.conf.json new file mode 100644 index 00000000..9dbcc96f --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossarify-md.conf.json @@ -0,0 +1,16 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv", + "dialect": { + "delimiter": ";", + "quoteChar": "#", + "escapeChar": "\\" + } + } + }] +} diff --git a/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.csv b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.csv new file mode 100644 index 00000000..26439581 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.csv @@ -0,0 +1,4 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#\#1#;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;GIVEN an '@id' field WITH text data containing a hash AND a skos:definition field NOT WITH quoted text data AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV input the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT required to be escaped with 'escapeChar' AND the output glossary term MUST have this record's term URI with one hash preceeding the ID number AND a term definition being equal to this definition. +#\#2#;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;GIVEN an '@id' field WITH text data containing a hash AND a skos:definition field WITH "quoted text data" AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV input the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT required to be escaped with 'escapeChar' AND the output glossary term MUST have this record's term URI with one hash preceeding the ID number AND a term definition being equal to this definition. +#\#3#;Imported Term 3;Alias 3.1,Alias 3.2,Alias 3.3;GIVEN an '@id' field with text data containing a hash AND a skos:definition field WITH "quoted text data embedding more "quoted text data"" AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT to be escaped with 'escapeChar' AND the output glossary term MUST have have this record's URI with one hash preceeding the ID number AND a term definition being equal to this definition. diff --git a/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossarify-md.conf.json new file mode 100644 index 00000000..4429b428 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossarify-md.conf.json @@ -0,0 +1,11 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }] +} diff --git a/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.csv b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.csv new file mode 100644 index 00000000..fb3f4b78 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.csv @@ -0,0 +1,4 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3; GIVEN a skos:definition WITH NOT quoted text data AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MAY NOT be surrounded by 'quoteChar' AND NO quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' AND MUST NOT be escaped with 'escapeChar' AND MUST be equal to this definition. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;"GIVEN a skos:definition WITH ""quoted text data"" AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MUST be surrounded by 'quoteChar' AND quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' anymore AND MUST NOT be escaped with 'escapeChar' anymore AND MUST be similar to 'quoted text data' except of the single quotes being quotes." +#3;Imported Term 3;Alias 3.1,Alias 3.2,Alias 3.3;"GIVEN a skos:definition WITH ""quoted text data embedding more ""quoted text data"""" AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MUST be surrounded by 'quoteChar' AND quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' anymore AND MUST NOT be escaped with 'escapeChar' anymore AND MUST be similar to 'quoted text data embedding more 'quoted text data'' except of the single quotes being quotes." diff --git a/test/input/config-glossaries/import-csv/with-trailing-delimiters/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-trailing-delimiters/glossarify-md.conf.json new file mode 100644 index 00000000..dee5d56b --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-trailing-delimiters/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-trailing-delimiters", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-trailing-delimiters/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-trailing-delimiters/glossary.csv b/test/input/config-glossaries/import-csv/with-trailing-delimiters/glossary.csv new file mode 100644 index 00000000..5c2c73d3 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-trailing-delimiters/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.; +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.; diff --git a/test/input/config-glossaries/import-csv/with-whitespaces/glossarify-md.conf.json b/test/input/config-glossaries/import-csv/with-whitespaces/glossarify-md.conf.json new file mode 100644 index 00000000..f793cf9c --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-whitespaces/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-whitespaces", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-whitespaces/terms.json" + } +} diff --git a/test/input/config-glossaries/import-csv/with-whitespaces/glossary.csv b/test/input/config-glossaries/import-csv/with-whitespaces/glossary.csv new file mode 100644 index 00000000..5e5582a1 --- /dev/null +++ b/test/input/config-glossaries/import-csv/with-whitespaces/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1 ; Imported Term 1 ; Alias 1.1,Alias 1.2,Alias 1.3 ; GIVEN separater surrouned by whitespaces THEN whitespaces should be trimmed from imported data. + #2; Imported Term 2 ; Alias 2.1,Alias 2.2,Alias 2.3 ; GIVEN a line with a leading whitespace THEN it should not produce an error. diff --git a/test/input/docs/references/document.md b/test/input/docs/references/document.md new file mode 100644 index 00000000..3bbd5949 --- /dev/null +++ b/test/input/docs/references/document.md @@ -0,0 +1,14 @@ +# Document + +GIVEN a file `references.md` +AND a complex heading reflecting IEEE citation style + +~~~ +###### C. E. Shannon, "A mathematical theory of communication," in The Bell System Technical Journal, vol. 27, no. 3, pp. 379-423, July 1948, doi: 10.1002/j.1538-7305.1948.tb01338.x. + +~~~ +AND a document `document.md` citing Shannon1948 +THEN the citation MUST be linked to `references.md`. \ No newline at end of file diff --git a/test/input/docs/references/glossarify-md.conf.json b/test/input/docs/references/glossarify-md.conf.json new file mode 100644 index 00000000..75811e46 --- /dev/null +++ b/test/input/docs/references/glossarify-md.conf.json @@ -0,0 +1,11 @@ +{ + "$schema": "../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../output-actual/docs/references", + "glossaries": [{ + "file": "./references.md" + }], + "linking": { + "headingIdAlgorithm": "md5-7" + } +} diff --git a/test/input/docs/references/references.md b/test/input/docs/references/references.md new file mode 100644 index 00000000..06529dfb --- /dev/null +++ b/test/input/docs/references/references.md @@ -0,0 +1,7 @@ +# References + +##### C. E. Shannon, "A mathematical theory of communication," in The Bell System Technical Journal, vol. 27, no. 3, pp. 379-423, July 1948, doi: 10.1002/j.1538-7305.1948.tb01338.x. + \ No newline at end of file diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossarify-md.conf.json new file mode 100644 index 00000000..19fa0dcd --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-array", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-array/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossary.csv new file mode 100644 index 00000000..bfafb90b --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:altLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1;Alias 1.2;Alias 1.3;GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term. +#2;Imported Term 2;Alias 2.1;Alias 2.2;Alias 2.3;GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term. diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossary.md b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossary.md new file mode 100644 index 00000000..37695ccd --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/glossary.md @@ -0,0 +1,19 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term. + +## [Imported Term 2](#imported-term-2) + + + +GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term. diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/terms.json b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/terms.json new file mode 100644 index 00000000..82084f92 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-array/terms.json @@ -0,0 +1,67 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term.", + "shortDesc": "GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term.", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Imported Term 1|Alias 1\\.1|Alias 1\\.2|Alias 1\\.3)/u", + "aliases": [ + "Alias 1.1", + "Alias 1.2", + "Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term.", + "shortDesc": "GIVEN multiple columns of skos:altLabel AND skos:altLabel maps to term aliases AND term aliases are an array property THEN the value of each column SHOULD become an alias of this term.", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Imported Term 2|Alias 2\\.1|Alias 2\\.2|Alias 2\\.3)/u", + "aliases": [ + "Alias 2.1", + "Alias 2.2", + "Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossarify-md.conf.json new file mode 100644 index 00000000..b2c98a76 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-scalar", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-columns-map-to-scalar/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.csv new file mode 100644 index 00000000..aecac6df --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition;skos:definition +#1;Imported Term 1;Alias 1.1, Alias 1.2, Alias 1.3;GIVEN multiple columns of skos:definition AND skos:definition maps to a term's definition AND a term definition is a scalar property THEN the value of none or the first or the last column SHOULD become the term's definition but not both.;Definition 1.2 +#2;Imported Term 2;Alias 2.1, Alias 2.2, Alias 2.3;GIVEN multiple columns of skos:definition AND skos:definition maps to a term's definition AND a term definition is a scalar property THEN the value of none or the first or the last column SHOULD become the term's definition but not both.;Definition 2.2 diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.md b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.md new file mode 100644 index 00000000..82d50b01 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/glossary.md @@ -0,0 +1,15 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +## [Imported Term 2](#imported-term-2) + + diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/terms.json b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/terms.json new file mode 100644 index 00000000..ab67dae2 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-map-to-scalar/terms.json @@ -0,0 +1,67 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Imported Term 1|Alias 1\\.1|Alias 1\\.2|Alias 1\\.3)/u", + "aliases": [ + "Alias 1.1", + "Alias 1.2", + "Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Imported Term 2|Alias 2\\.1|Alias 2\\.2|Alias 2\\.3)/u", + "aliases": [ + "Alias 2.1", + "Alias 2.2", + "Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossarify-md.conf.json new file mode 100644 index 00000000..08d5c281 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossarify-md.conf.json @@ -0,0 +1,24 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-columns-partly-not-skos", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv", + "schema": { + "fields": [ + {"name": "@id"} + ,{"name": "ignore"} + ,{"name": "ignore"} + ,{"name": "http://www.w3.org/2004/02/skos/core#prefLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#altLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#definition"} + ] + } + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-columns-partly-not-skos/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.csv new file mode 100644 index 00000000..38abd27a --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.csv @@ -0,0 +1,2 @@ +#1;IGNORE-1.1;IGNORE-1.2;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;IGNORE-2.1;IGNORE-2.2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.md b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.md new file mode 100644 index 00000000..e76f8bb5 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/glossary.md @@ -0,0 +1,19 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +The short definition of a term. The long definition of a term contains both sentences. + +## [Imported Term 2](#imported-term-2) + + + +The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/terms.json b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/terms.json new file mode 100644 index 00000000..32fe4ba9 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-columns-partly-not-skos/terms.json @@ -0,0 +1,63 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "The short definition of a term. The long definition of a term contains both sentences.", + "shortDesc": "The short definition of a term.", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Alias 1\\.1,Alias 1\\.2,Alias 1\\.3|Imported Term 1)/u", + "aliases": [ + "Alias 1.1,Alias 1.2,Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "The short definition of a term. The long definition of a term contains both sentences.", + "shortDesc": "The short definition of a term.", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Alias 2\\.1,Alias 2\\.2,Alias 2\\.3|Imported Term 2)/u", + "aliases": [ + "Alias 2.1,Alias 2.2,Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossarify-md.conf.json new file mode 100644 index 00000000..daed88d3 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossarify-md.conf.json @@ -0,0 +1,18 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-custom-delimiter", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv", + "dialect": { + "delimiter": "|", + "doubleQuote": true + } + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-custom-delimiter/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossary.csv new file mode 100644 index 00000000..21e56214 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossary.csv @@ -0,0 +1,2 @@ +@id|skos:prefLabel|skos:altLabel|skos:definition +#1|Imported Term 1| Alias 1.1,Alias 1.2,Alias 1.3|GIVEN a custom separator '|' THEN columns should still be imported correctly. diff --git a/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossary.md b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossary.md new file mode 100644 index 00000000..8bbffcf9 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/glossary.md @@ -0,0 +1,10 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +GIVEN a custom separator '|' THEN columns should still be imported correctly. diff --git a/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/terms.json b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/terms.json new file mode 100644 index 00000000..1b43e659 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-custom-delimiter/terms.json @@ -0,0 +1,42 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "GIVEN a custom separator '|' THEN columns should still be imported correctly.", + "shortDesc": "GIVEN a custom separator '|' THEN columns should still be imported correctly.", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Alias 1\\.1,Alias 1\\.2,Alias 1\\.3|Imported Term 1)/u", + "aliases": [ + "Alias 1.1,Alias 1.2,Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossarify-md.conf.json new file mode 100644 index 00000000..eca28cb7 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-prefixes", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-prefixes/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossary.csv new file mode 100644 index 00000000..7066b072 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossary.md b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossary.md new file mode 100644 index 00000000..e76f8bb5 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/glossary.md @@ -0,0 +1,19 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +The short definition of a term. The long definition of a term contains both sentences. + +## [Imported Term 2](#imported-term-2) + + + +The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/terms.json b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/terms.json new file mode 100644 index 00000000..32fe4ba9 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-prefixes/terms.json @@ -0,0 +1,63 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "The short definition of a term. The long definition of a term contains both sentences.", + "shortDesc": "The short definition of a term.", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Alias 1\\.1,Alias 1\\.2,Alias 1\\.3|Imported Term 1)/u", + "aliases": [ + "Alias 1.1,Alias 1.2,Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "The short definition of a term. The long definition of a term contains both sentences.", + "shortDesc": "The short definition of a term.", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Alias 2\\.1,Alias 2\\.2,Alias 2\\.3|Imported Term 2)/u", + "aliases": [ + "Alias 2.1,Alias 2.2,Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossarify-md.conf.json new file mode 100644 index 00000000..1e521aa5 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-uris", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-and-uris/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossary.csv new file mode 100644 index 00000000..1196fd9b --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossary.csv @@ -0,0 +1,3 @@ +@id;http://www.w3.org/2004/02/skos/core#prefLabel;http://www.w3.org/2004/02/skos/core#altLabel;http://www.w3.org/2004/02/skos/core#definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced. diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossary.md b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossary.md new file mode 100644 index 00000000..adce0e4f --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/glossary.md @@ -0,0 +1,19 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced. + +## [Imported Term 2](#imported-term-2) + + + +GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced. diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/terms.json b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/terms.json new file mode 100644 index 00000000..511f6bac --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-and-uris/terms.json @@ -0,0 +1,63 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced.", + "shortDesc": "GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced.", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Alias 1\\.1,Alias 1\\.2,Alias 1\\.3|Imported Term 1)/u", + "aliases": [ + "Alias 1.1,Alias 1.2,Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced.", + "shortDesc": "GIVEN a CSV file with headers AND headers use the authoritative URIs of SKOS terms THEN table columns MUST be interpreted according to the meaning of the SKOS term referenced.", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Alias 2\\.1,Alias 2\\.2,Alias 2\\.3|Imported Term 2)/u", + "aliases": [ + "Alias 2.1,Alias 2.2,Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossarify-md.conf.json new file mode 100644 index 00000000..2b8fcefe --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossarify-md.conf.json @@ -0,0 +1,26 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-configured", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + ,"dialect": { + "delimiter": ";", + "doubleQuote": true + } + ,"schema": { + "fields": [ + {"name": "@id"} + ,{"name": "http://www.w3.org/2004/02/skos/core#prefLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#altLabel"} + ,{"name": "http://www.w3.org/2004/02/skos/core#definition"} + ] + } + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-configured/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossary.csv new file mode 100644 index 00000000..b76e0949 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossary.csv @@ -0,0 +1,2 @@ +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossary.md b/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossary.md new file mode 100644 index 00000000..e76f8bb5 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-configured/glossary.md @@ -0,0 +1,19 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +The short definition of a term. The long definition of a term contains both sentences. + +## [Imported Term 2](#imported-term-2) + + + +The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-configured/terms.json b/test/output-expected/config-glossaries/import-csv/with-headers-configured/terms.json new file mode 100644 index 00000000..32fe4ba9 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-configured/terms.json @@ -0,0 +1,63 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "The short definition of a term. The long definition of a term contains both sentences.", + "shortDesc": "The short definition of a term.", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Alias 1\\.1,Alias 1\\.2,Alias 1\\.3|Imported Term 1)/u", + "aliases": [ + "Alias 1.1,Alias 1.2,Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "The short definition of a term. The long definition of a term contains both sentences.", + "shortDesc": "The short definition of a term.", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Alias 2\\.1,Alias 2\\.2,Alias 2\\.3|Imported Term 2)/u", + "aliases": [ + "Alias 2.1,Alias 2.2,Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossarify-md.conf.json new file mode 100644 index 00000000..fb5d1a46 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-headers-missing", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-headers-missing/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossary.csv new file mode 100644 index 00000000..b76e0949 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossary.csv @@ -0,0 +1,2 @@ +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;The short definition of a term. The long definition of a term contains both sentences. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;The short definition of a term. The long definition of a term contains both sentences. diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossary.md b/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossary.md new file mode 100644 index 00000000..44b53ccf --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-missing/glossary.md @@ -0,0 +1 @@ +# [Glossary](#glossary) diff --git a/test/output-expected/config-glossaries/import-csv/with-headers-missing/terms.json b/test/output-expected/config-glossaries/import-csv/with-headers-missing/terms.json new file mode 100644 index 00000000..1118440d --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-headers-missing/terms.json @@ -0,0 +1,21 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossarify-md.conf.json new file mode 100644 index 00000000..9dbcc96f --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossarify-md.conf.json @@ -0,0 +1,16 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv", + "dialect": { + "delimiter": ";", + "quoteChar": "#", + "escapeChar": "\\" + } + } + }] +} diff --git a/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.csv new file mode 100644 index 00000000..26439581 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.csv @@ -0,0 +1,4 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#\#1#;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;GIVEN an '@id' field WITH text data containing a hash AND a skos:definition field NOT WITH quoted text data AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV input the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT required to be escaped with 'escapeChar' AND the output glossary term MUST have this record's term URI with one hash preceeding the ID number AND a term definition being equal to this definition. +#\#2#;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;GIVEN an '@id' field WITH text data containing a hash AND a skos:definition field WITH "quoted text data" AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV input the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT required to be escaped with 'escapeChar' AND the output glossary term MUST have this record's term URI with one hash preceeding the ID number AND a term definition being equal to this definition. +#\#3#;Imported Term 3;Alias 3.1,Alias 3.2,Alias 3.3;GIVEN an '@id' field with text data containing a hash AND a skos:definition field WITH "quoted text data embedding more "quoted text data"" AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT to be escaped with 'escapeChar' AND the output glossary term MUST have have this record's URI with one hash preceeding the ID number AND a term definition being equal to this definition. diff --git a/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.md b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.md new file mode 100644 index 00000000..1a6ac6cf --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossary.md @@ -0,0 +1,28 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +GIVEN an '@id' field WITH text data containing a hash AND a skos:definition field NOT WITH quoted text data AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV input the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT required to be escaped with 'escapeChar' AND the output glossary term MUST have this record's term URI with one hash preceeding the ID number AND a term definition being equal to this definition. + +## [Imported Term 2](#imported-term-2) + + + +GIVEN an '@id' field WITH text data containing a hash AND a skos:definition field WITH "quoted text data" AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV input the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT required to be escaped with 'escapeChar' AND the output glossary term MUST have this record's term URI with one hash preceeding the ID number AND a term definition being equal to this definition. + +## [Imported Term 3](#imported-term-3) + + + +GIVEN an '@id' field with text data containing a hash AND a skos:definition field WITH "quoted text data embedding more "quoted text data"" AND 'quoteChar' (custom) being the hash character AND 'escapeChar' (custom) being the backslash character THEN in CSV the '@id' field value MUST be surrounded by 'quoteChar' (hash) AND its hash text data MUST be escaped by 'escapeChar' (backslash) AND skos:definition text data is NOT required to be surrounded by 'quoteChar' AND NOT to be escaped with 'escapeChar' AND the output glossary term MUST have have this record's URI with one hash preceeding the ID number AND a term definition being equal to this definition. diff --git a/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossarify-md.conf.json new file mode 100644 index 00000000..4429b428 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossarify-md.conf.json @@ -0,0 +1,11 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }] +} diff --git a/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.csv new file mode 100644 index 00000000..fb3f4b78 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.csv @@ -0,0 +1,4 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3; GIVEN a skos:definition WITH NOT quoted text data AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MAY NOT be surrounded by 'quoteChar' AND NO quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' AND MUST NOT be escaped with 'escapeChar' AND MUST be equal to this definition. +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;"GIVEN a skos:definition WITH ""quoted text data"" AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MUST be surrounded by 'quoteChar' AND quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' anymore AND MUST NOT be escaped with 'escapeChar' anymore AND MUST be similar to 'quoted text data' except of the single quotes being quotes." +#3;Imported Term 3;Alias 3.1,Alias 3.2,Alias 3.3;"GIVEN a skos:definition WITH ""quoted text data embedding more ""quoted text data"""" AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MUST be surrounded by 'quoteChar' AND quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' anymore AND MUST NOT be escaped with 'escapeChar' anymore AND MUST be similar to 'quoted text data embedding more 'quoted text data'' except of the single quotes being quotes." diff --git a/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.md b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.md new file mode 100644 index 00000000..e6de0768 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossary.md @@ -0,0 +1,28 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +GIVEN a skos:definition WITH NOT quoted text data AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MAY NOT be surrounded by 'quoteChar' AND NO quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' AND MUST NOT be escaped with 'escapeChar' AND MUST be equal to this definition. + +## [Imported Term 2](#imported-term-2) + + + +GIVEN a skos:definition WITH "quoted text data" AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MUST be surrounded by 'quoteChar' AND quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' anymore AND MUST NOT be escaped with 'escapeChar' anymore AND MUST be similar to 'quoted text data' except of the single quotes being quotes. + +## [Imported Term 3](#imported-term-3) + + + +GIVEN a skos:definition WITH "quoted text data embedding more "quoted text data"" AND 'quoteChar' (default) being the quote character AND 'escapeChar' (default) being the quote character, too, THEN the CSV text data MUST be surrounded by 'quoteChar' AND quote chars within the text data MUST be escaped by 'escapeChar' AND the glossary term definition output MUST NOT be surrounded by 'quoteChar' anymore AND MUST NOT be escaped with 'escapeChar' anymore AND MUST be similar to 'quoted text data embedding more 'quoted text data'' except of the single quotes being quotes. diff --git a/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossarify-md.conf.json new file mode 100644 index 00000000..dee5d56b --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-trailing-delimiters", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-trailing-delimiters/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossary.csv new file mode 100644 index 00000000..5c2c73d3 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1;Imported Term 1;Alias 1.1,Alias 1.2,Alias 1.3;GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.; +#2;Imported Term 2;Alias 2.1,Alias 2.2,Alias 2.3;GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.; diff --git a/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossary.md b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossary.md new file mode 100644 index 00000000..9d3d21dd --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/glossary.md @@ -0,0 +1,19 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.; + +## [Imported Term 2](#imported-term-2) + + + +GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.; diff --git a/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/terms.json b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/terms.json new file mode 100644 index 00000000..627b0b10 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-trailing-delimiters/terms.json @@ -0,0 +1,63 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.;", + "shortDesc": "GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.;", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Alias 1\\.1,Alias 1\\.2,Alias 1\\.3|Imported Term 1)/u", + "aliases": [ + "Alias 1.1,Alias 1.2,Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.;", + "shortDesc": "GIVEN a CSV file WITH trailing delimiters ';' THEN it MUST import terms nonetheless.;", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Alias 2\\.1,Alias 2\\.2,Alias 2\\.3|Imported Term 2)/u", + "aliases": [ + "Alias 2.1,Alias 2.2,Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossarify-md.conf.json b/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossarify-md.conf.json new file mode 100644 index 00000000..f793cf9c --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossarify-md.conf.json @@ -0,0 +1,14 @@ +{ + "$schema": "../../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../../output-actual/config-glossaries/import-csv/with-whitespaces", + "glossaries": [{ + "file": "./glossary.md", + "import": { + "file": "./glossary.csv" + } + }], + "dev": { + "termsFile": "../../../../output-actual/config-glossaries/import-csv/with-whitespaces/terms.json" + } +} diff --git a/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossary.csv b/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossary.csv new file mode 100644 index 00000000..5e5582a1 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossary.csv @@ -0,0 +1,3 @@ +@id;skos:prefLabel;skos:altLabel;skos:definition +#1 ; Imported Term 1 ; Alias 1.1,Alias 1.2,Alias 1.3 ; GIVEN separater surrouned by whitespaces THEN whitespaces should be trimmed from imported data. + #2; Imported Term 2 ; Alias 2.1,Alias 2.2,Alias 2.3 ; GIVEN a line with a leading whitespace THEN it should not produce an error. diff --git a/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossary.md b/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossary.md new file mode 100644 index 00000000..26efab62 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-whitespaces/glossary.md @@ -0,0 +1,19 @@ +# [Glossary](#glossary) + +## [Imported Term 1](#imported-term-1) + + + +GIVEN separater surrouned by whitespaces THEN whitespaces should be trimmed from imported data. + +## [Imported Term 2](#imported-term-2) + + + +GIVEN a line with a leading whitespace THEN it should not produce an error. diff --git a/test/output-expected/config-glossaries/import-csv/with-whitespaces/terms.json b/test/output-expected/config-glossaries/import-csv/with-whitespaces/terms.json new file mode 100644 index 00000000..3821da61 --- /dev/null +++ b/test/output-expected/config-glossaries/import-csv/with-whitespaces/terms.json @@ -0,0 +1,63 @@ +[ + { + "value": "Glossary", + "uri": "/glossary", + "valueHash8": "31d109d1", + "hint": "", + "longDesc": "", + "shortDesc": "", + "headingId": "glossary", + "headingIdPlain": "", + "headingDepth": 1, + "anchor": "#glossary", + "regex": "/(Glossary)/u", + "aliases": [], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 1", + "uri": "/#1", + "valueHash8": "c8c7f905", + "hint": "", + "longDesc": "GIVEN separater surrouned by whitespaces THEN whitespaces should be trimmed from imported data.", + "shortDesc": "GIVEN separater surrouned by whitespaces THEN whitespaces should be trimmed from imported data.", + "headingId": "imported-term-1", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-1", + "regex": "/(Alias 1\\.1,Alias 1\\.2,Alias 1\\.3|Imported Term 1)/u", + "aliases": [ + "Alias 1.1,Alias 1.2,Alias 1.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + }, + { + "value": "Imported Term 2", + "uri": "/#2", + "valueHash8": "dbf4905e", + "hint": "", + "longDesc": "GIVEN a line with a leading whitespace THEN it should not produce an error.", + "shortDesc": "GIVEN a line with a leading whitespace THEN it should not produce an error.", + "headingId": "imported-term-2", + "headingIdPlain": "", + "headingDepth": 2, + "anchor": "#imported-term-2", + "regex": "/(Alias 2\\.1,Alias 2\\.2,Alias 2\\.3|Imported Term 2)/u", + "aliases": [ + "Alias 2.1,Alias 2.2,Alias 2.3" + ], + "ignoreCase": false, + "countOccurrenceTotal": 0, + "type": "term-definition", + "file": "glossary.md", + "termHint": "" + } +] diff --git a/test/output-expected/docs/references/document.md b/test/output-expected/docs/references/document.md new file mode 100644 index 00000000..8bb73681 --- /dev/null +++ b/test/output-expected/docs/references/document.md @@ -0,0 +1,15 @@ +# [Document](#md5-0a9a7c4) + +GIVEN a file `references.md` +AND a complex heading reflecting IEEE citation style + + ###### C. E. Shannon, "A mathematical theory of communication," in The Bell System Technical Journal, vol. 27, no. 3, pp. 379-423, July 1948, doi: 10.1002/j.1538-7305.1948.tb01338.x. + + +AND a document `document.md` citing [Shannon1948][1] +THEN the citation MUST be linked to `references.md`. + +[1]: ./references.md#md5-68189da diff --git a/test/output-expected/docs/references/glossarify-md.conf.json b/test/output-expected/docs/references/glossarify-md.conf.json new file mode 100644 index 00000000..75811e46 --- /dev/null +++ b/test/output-expected/docs/references/glossarify-md.conf.json @@ -0,0 +1,11 @@ +{ + "$schema": "../../../../conf/v5/schema.json", + "baseDir": ".", + "outDir": "../../../output-actual/docs/references", + "glossaries": [{ + "file": "./references.md" + }], + "linking": { + "headingIdAlgorithm": "md5-7" + } +} diff --git a/test/output-expected/docs/references/references.md b/test/output-expected/docs/references/references.md new file mode 100644 index 00000000..32758357 --- /dev/null +++ b/test/output-expected/docs/references/references.md @@ -0,0 +1,8 @@ +# [References](#md5-540bb2d) + +##### [C. E. Shannon, "A mathematical theory of communication," in The Bell System Technical Journal, vol. 27, no. 3, pp. 379-423, July 1948, doi: 10.1002/j.1538-7305.1948.tb01338.x.](#md5-68189da) + + diff --git a/test/package.json b/test/package.json index 36cff564..86aa198b 100644 --- a/test/package.json +++ b/test/package.json @@ -178,7 +178,20 @@ "test_p21__05": "node . --config ./input/config-linking/pathRewrites-absolute/array-regexp-recursive-1/glossarify-md.conf.json", "test_p21__06": "node . --config ./input/config-linking/pathRewrites-absolute/array-regexp-recursive-2/glossarify-md.conf.json", "test_p22__00": "node . --config ./input/config-linking/pathRewrites-image/glossarify-md.conf.json", - "test_p23__00": "node . --config ./input/docs-hugo/shortcodes/glossarify-md.conf.json", + "test_p23__00": "node . --config ./input/docs/references/glossarify-md.conf.json", + "test_p23__01": "node . --config ./input/docs-hugo/shortcodes/glossarify-md.conf.json", + "test_p24__00": "node . --config ./input/config-glossaries/import-csv/with-headers-missing/glossarify-md.conf.json", + "test_p24__01": "node . --config ./input/config-glossaries/import-csv/with-headers-and-uris/glossarify-md.conf.json", + "test_p24__02": "node . --config ./input/config-glossaries/import-csv/with-headers-and-prefixes/glossarify-md.conf.json", + "test_p24__03": "node . --config ./input/config-glossaries/import-csv/with-headers-configured/glossarify-md.conf.json", + "test_p24__04": "node . --config ./input/config-glossaries/import-csv/with-whitespaces/glossarify-md.conf.json", + "test_p24__05": "node . --config ./input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-default/glossarify-md.conf.json", + "test_p24__06": "node . --config ./input/config-glossaries/import-csv/with-quoteChar-and-escapeChar-custom/glossarify-md.conf.json", + "test_p24__07": "node . --config ./input/config-glossaries/import-csv/with-custom-delimiter/glossarify-md.conf.json", + "test_p24__08": "node . --config ./input/config-glossaries/import-csv/with-trailing-delimiters/glossarify-md.conf.json", + "test_p24__09": "node . --config ./input/config-glossaries/import-csv/with-columns-partly-not-skos/glossarify-md.conf.json", + "test_p24__10": "node . --config ./input/config-glossaries/import-csv/with-columns-map-to-array/glossarify-md.conf.json", + "test_p24__11": "node . --config ./input/config-glossaries/import-csv/with-columns-map-to-scalar/glossarify-md.conf.json", "postsuite": "npm run diff", "postat": "npm run diff", "diff": "git diff --minimal --color --no-index --ignore-cr-at-eol ./output-expected ./output-actual | node difftest.js",