4

Both Daring Fireball and Markdown Guide suggest that in Markdown writing, reference-style links can be put at the end of the document (say) or right after the reference is made. My question arises when you might want to use those same links across different documents. You could, of course, copy and paste them into each document, but that's logically not as good as keeping them all in just one central place, where they can be commonly updated and managed, and then just being able to refer to the needed links from different Markdown documents.

If these references weren't links, but were full-blown bibliographic references, then BibTeX or Zotero might be used. But that seems a bit heavy-handed — for one thing, you'd then also have to go to Pandoc and friends to process the references. I'm thinking of something much more lightweight, just Markdown to Markdown.

Has anyone out there developed a workflow or tool that uses common reference-style links across Markdown documents? A BibTeX for URLs in Markdown?

Laurel
  • 4,283
  • 3
  • 13
  • 42
Danny Quah
  • 41
  • 2

1 Answers1

1

Although it is not exactly "lightweight", I think the best thought-out (and best supported) workflow will consist of Pandoc and use its citation management, consisting of two (three) parts:

1. Citations syntax

Which markup to put into your Markdown documents: this would look something like:

Important thing that needs lots of sources [@doe99; @smith2000; @smith2004].

or

@smith2004 state that thing is very important.

Possibly decorated with some location specifiers (e.g. pages or chapters within that source).

2. Bibliographic data

Your actual data that a citation wants to reference. Bib(La)TeX is the historical standard with lots of gotcha's concerning - not only - capitalization and names:

@Electronic{OSM,
  Title = {{OpenStreetMap} database},
  Author = {John Doe and Jane Smith and Johannes Diderik {van der Waals} and {{OpenStreetMap} contributors}},
  Note = {Licensed under the Open Data Commons Open Database License (ODbL) by the OpenStreetMap Foundation (OSMF)},
  Url = {https://www.openstreetmap.org/},
  Year = {Accessed 2022--2025}
}

Manual maintenance is labor-intensive, but there is very good tool support. Random plug for JabRef which - like its competitors makes handling of such a database file bearable.

Newer and hotter is a JSON/YAML based metadata format, which is much more conducive to (semi-)manual maintenance.

references:
- id: Smith2004
  author:
    - family: Smith
      given: Jon F.
    - family: Doe
      given: Jane
  DOI: 12.3456/111222333-444
  editor:
    - family: van der Waals
      given: Johannes Diderik
  issued:
    - year: 2019
  language: en
  page: 42-98
  publisher: 'Santa Pub Inc.'
  publisher-place: 'North Pole, Earth'
  source: Crossref
  title: >-
    Super-long title that nicely shows how to wrap
    such long strings in YAML
  type: chapter
  URL: 'https://example.com/the-book/chp11'

I cannot judge how good tool support is for that - it seems to be quite new.

3. CSL style definition

This defines how citation syntax + bibliographic information is actually rendered in an output format (footnote + bibliography chapter, footnotes only, bibliography only, citation marker like [1], (2) or (Smith, 2021) and where and how any location specifiers (page numbers, cauthor-year]hapters) look like.

This of course also depends on the output format, be it Markdown, DOCX, PDF or HTML.

ojdo
  • 111
  • 3