Skip to content

Markdown Term

Author: Michael Vorburger.ch
Status: Deprecated

Abstract

This Spec defines a Markdown syntax extension to mark up Terms.

This is useful in order to use Markdown to write knowledge management articles.

It builds upon and extends the Markdown Magic Links spec.

Description

Links like ?[[../concepts/xyz.md]], note the ? question mark prefix, are transformed into (something) like:

<a
  href="../concepts/xyz.md"
  title="(A longer description about XYZ to appear on mouse hover over, not just its TITLE)"
  class="some style with dotted underline, and another color than other links">
  XYZ</a>

In practice and just for end-user convenience, we expect this to often be used together either with Workspace URL References (for example as ?[[¬/xyz]]), or the CURIE syntax (for example as ?[[term:xyz]], where term is configured somewhere as a prefix e.g. for ¬/concepts/).

Alternatives

Mouse Over

Alternatively, a Markdown pre-processor could just always set a title= on all links, not just these.

Automagic

Instead of introducing a special link syntax, if a system “knew” that e.g. "../concepts/xyz.md" is a Term it could automagically use another CSS class style on links.

One way to declare that could be a $type: Term sort of declaration e.g. in YAML-LD Frontmatter.

Such a system could then also generate e.g. an alphabetically sorted “Glossary” using HTML <dl> <dt> <dd> markup.

Marker Character

We considered which “marker” character to use as prefix, and settled on ? after considering:

  • / would be confusing both before and inside [[
  • ! is used for inline images; e.g. ![Image](http://example.org/image.png)
  • ^ is used for footnotes by at least some Markdown processors
  • @ is often used to “raise” (or “tag”) people
  • $ implies “money” (or “value”)
  • % was no better than ?
  • & marks an anchor in YAML
  • # is anchor in URL

Fallback

One could manually write out such HTML for each Term within each MD, but that seems quite tedious.

Implementations

Enola.dev’s Markdown pre-processor may implement this idea in the future.

References

As far as we know, this is a novel idea which isn’t been used anywhere that we are aware of.