feature: Bibliography and citation support

[Kabouik]

Problem:

I haven't found a way to cite references using a .bib library. Is that possible?

Solution:

I don't have a long experience on how this should be done since I am currently transitioning to Bibtex/Biblatex (with cobib as manager) from Zotero myself, and md-to-pdf is actually a great way to generate nice PDF files without the heavy LaTeX suite. My understanding is it is usually done by indicating the path to a .bib file in the front-matter, and then cite references with their unique Bibtex/Biblatex identifier, usually in the form @author_keyword_year.

You can see an example here with a paper written in .Rmd.

I am not sure exactly if LaTeXand pandoc are the only way to use this, or if there are lighter alternatives that md-to-pdf might already support. Same goes for title: and author: sections in the front-matter, I know they work with pandoc without the need for any LaTeX installation, but I don't know what are the dependencies under the hood; those fields would be pretty useful for md-to-pdf too.

Would there be any way to add support for bibliography options?

[simonhaenisch]

Yeah it's probably all possible but it's not very trivial. md-to-pdf is pretty extensible, if you use a .js config file. You can pass a custom parser, renderer, etc. to marked (see https://marked.js.org/#/USING_PRO.md). You could probably write a custom parser (and/or lexer?) for @author_keyword_year and then fs.readFile('some.bib') to look up the citation in the bibliography, and use a custom renderer to render it. Maybe there's even someone who did that already and you can integrate it.

I've been wanting to do some refactoring around extensibility, especially to implement the new marked.use() API, and then start including some officially maintained plugins as part of this package. But I'm lacking time to maintain this package at the moment. You can look through some of the closed issues though, there's multiple comments of me with examples for how to pass a custom marked renderer.

Just let me say that there's online editors out there which make working with LaTeX quite pleasant... I've used ShareLaTeX (now Overleaf) to write my master thesis, a scientific paper and other stuff. It has a live preview of your document, pretty fast re-renders, and you don't need to install anything. md-to-pdf has some limitations when it comes to page layout, page breaks and so on, which is all basic stuff that you don't even have to think about with LaTeX.

The way I've done citations for some homework in the past is, because they were usually just a few pages, I'd collect all the references on the last page and push them to the bottom with a div.

Lorem ipsum "dolor sit amet" [1, p. 78-79], consectetur adipiscing elit.

<div style="height: 25cm;"></div>

---

[1] Miles, Rebekah L. 1997. "The Instrumental Role of Reason." In _Wesley and the Quadrilateral: Renewing the Conversation_, edited by W. Stephen Gunter; Scott J. Jones, contributor; with Ted A. Campbell, Rebekah Miles, and Stephen A. Gunter. Nashville: Abingdon.

[Kabouik]

Thanks a lot for the detailed answer, it's greatly appreciated. I am afraid I don't have the skills to use the extensions you mentioned, but I'll have a look just in case I can understand how to make it work.

---

I know about those web alternatives but I would like to avoid that for several reasons. I have been trying to use one in the past. I forgot its name, it changed several times in the past, and that is part of the very problem. First, the features have been changing over time depending on which company bought the remnants of the previous iteration, sometimes hidden behind paywalls, and my institution won't pay subscriptions for tools like that. Not that I would want to depend on a paid plan anyway, it's not good for the long term since you can't tell whether the service will be available in the future. For instance, collaborative work features with track changes and simultaneous edition really look great, but are not available on the free plan. Additionally, I don't think my institution would allow relying on a third-party private company and their servers for editing my documents online (they do trust Microsoft and their online solution, however :\). Finally, another problem with these solutions is users depend on whether the companies offering those services are economically robust enough to persist on the long term and not change their plans or features over time, which I have observed with the few markdown online editors I checked out in the past. One's workflow can quickly be tied to their solution, and even when the format one is using is quite standard like LaTeX, there are still features that the work has been based on that won't be easily ported to local solutions if the service is suddenly changed or closed.

While I think those tools are really cool and well polished, there are too many reasons keeping me from committing to using them as my base editors. Another one is I need offline edition too. With local and open source software (kakoune text editor, md-to-pdf, pandoc, mupdf), I've already set up something that works quite well in my environment, with live PDF previews and clean, clutter-free, windows:

While this lacks the track change features I've seen in Overleaf (that's a great feature) and bibliography/citations mentioned in this issue, I believe that's a very flexible workflow since everything is tailored to my needs in .rc or config files, and it works on all my devices after I synchronize my dotfiles (online editors would work on all devices too, admittedly). Perhaps using LaTeX would be the best way to get all the things I would need locally, but if I could get md-to-pdf to support citations, that'd be pretty close to what I need with simpler syntax and lighter software, despite the limitations you mentioned.

[simonhaenisch]

Thanks for explaining the context. I like that setup you have there on the screenshot! 👌

I'll definitely leave this issue open, it's not the only LaTeX-like feature I would like to add (if you've browsed the issues, you might have seen that I wanted to TOC generation, automatic numbering of headings, etc.). But as I said I barely have enough time to maintain this project, let alone add new features. On top of that, currently I don't have the need for those features anymore (this initially started out as a tool to write some non-scientific homework, because I hated Office 365). So the best I will be able to do in the next few months is to make this package more extensible (i. e. plugins), and add some example plugins/recipes for doing so.

P. S. it would actually be great to make md-to-pdf into a very good LaTeX alternative.