From 02ac39db553c13639656e06d3a90d52ad10f2770 Mon Sep 17 00:00:00 2001 From: constantinos Date: Sat, 15 Jul 2023 15:56:00 +0300 Subject: [PATCH] workflow for working with Bibliographic references in MD !publish! --- content/article/md-workflow.md | 166 +++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 content/article/md-workflow.md diff --git a/content/article/md-workflow.md b/content/article/md-workflow.md new file mode 100644 index 0000000..0b25957 --- /dev/null +++ b/content/article/md-workflow.md @@ -0,0 +1,166 @@ +--- +title: "Markdown Workflow" +date: "2023-07-14T20:21:29+03:00" +author: "anybody" +contributors: ["constantinos-miltiadis.md"] +draft: true +keywords: + - guide + - markdown guide +abstract: | + This article outlines a workfow for compiling bibliography for articles written in Markdown. All tools involved are free, open source, and cross platform. +--- + +[Better Bibtex]: https://retorque.re/zotero-better-bibtex/ "Extension for Zotero for managic bibliographic data ." +[Zotero]: https://www.zotero.org/ "free and open source, cross-platform citation management software." +[Pandoc]: https://pandoc.org/ "universal document converter." +# Introduction + +This guide describes how to work with bibliographic references in ![Markdown](article:markdown-formatting) writing workflows. It outlines how to incorporate references, and how compile and export in various document formats (PDF, DOCX, MD, etc.), using any formal citation style. +All tools involved are free, open source, and cross-platform. + +# Requirements + +1. Some Markdown editor (see ![Markdown guide](article:markdown-formatting)). +2. [Zotero][] -- free and open source cross platform citation management software. +3. [Better Bibtex] -- "an extension for Zotero ... that makes it easier to manage bibliographic data, especially for people authoring documents using text-based toolchains (e.g. based on [LaTeX](https://www.latex-project.org/) / [Markdown](https://www.markdownguide.org/)"). +4. [Pandoc][] -- command line tool; "universal document converter". + + +# Aggregate and export bibliography collection + +The following outlines how to generate a `bib` file from a Zotero collection: + +1. In Zotero, create a new collection (titled say `mycollection`), and add all the items you want to reference in your document. +2. With [Zotero][] and [Better Bibtex][] installed, each entry in your Zotero database should have citation key: + ![](/markdown-guide/zotero-citation-key.png) +3. To reference an item in a Markdown file, just prefix the citation key with the \@ sign, as in `@khaled2018`. + 1. To add parentheses to a reference use square brackets, as in `[@khaled2018]` + 2. For multiple citations, separate keys with semicolons, as in `@khaled2018;@graziano2019` + 3. To add a page or a note before or after a citation do `see @graziano2019 p.125` +4. To export your reference collection, select the collection, right-click > Export Collection, select **Better BibLatex** (uncheck all options; background export optional): + ![](/markdown-guide/zotero-export-options.png) +3. Save your collection, e.g. as `mycollection.bib` . The resulting file is a set of citation keys, each with its own citation metadata (you can preview the file with a text editor). + +Notes: +- In case you modified your Zotero collection (included more items or edited existing itmes), re-export the collection and overwrite the previous `bib` file. +- BibTex export format will omit URLs associated with an entry! *Opt for BibLaTex export format.* +- The format of citation keys can be changed in the [Better Bibtex][] preferences (Zotero: Tools > Better BibTex > Open preferences). A minimal format is `auth.lower+year`. + +# Get a citation style file (CSL) + +Download a citation style file (CSL), from [the official citation style repository](https://github.com/citation-style-language/styles) (GitHub repository), or from the [Zotero Style Repository](https://www.zotero.org/styles) (search interface). + +# Gather files + +[^dir]: One way to get the absolute path of a file, is to drag and drop a file into a terminal (e.g. *PowerShell* in Windows and *Terminal* in macOS). Select the path that will appear, and right click, copy. + +- Optional good practices: + - Gather your document, bibliography, and CSL files in the same directory, say `/mydocument/`. + - Place images inside a subdirectory, e.g. `/mydocument/graphics/` + - Make a subdirectory for exported documents e.g. `/mydocument/export/` + - Avoid using spaces in directory or file names. +- Make sure that images referenced in the Markdown document use a the correct file path. +- Gather file paths for your MD, CSL, and BIB files.[^dir] + - Markdown file: + ``` + "/path/to/my-article.md" + ``` + - Bibliography bib file: + ``` + "/path/to/mycollection.bib" + ``` + - Citation style file: + ``` + "/path/to/reference-style.csl" + ``` + +Notes: +- Enclosing file paths within "quotes" is optional. However, using paths inside quotes can bypass the need for special characters in case of spaces in file or directory names. +- You can use both absolute paths to files, or relative paths. However, for relative paths, pandoc commands will need to be executed from the base directory that the relative paths. + +# Test Pandoc and your Markdown document + +Open a terminal: +- to test that [Pandoc][] works do: + ``` + pandoc --version + ``` +- to test that your Markdown document is in order do (this will not compile the bibliography): + ``` + For docx export: + pandoc "path/to/my-article.md" -o "/path/for/export.docx" + + or for pdf export: + pandoc "path/to/my-article.md" -o "/path/for/export.pdf" + + or for Markdown export: + pandoc "path/to/my-article.md" -o -o "/path/to/export-document.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd-citations --standalone + ``` + +# Compile document with bibliographic references + +To compile a new document file including citations and bibliography in Markdown do: + +``` +pandoc "path/to/myarticle.md" --citeproc --bibliography "/path/to/mycollection.bib" --csl "/path/to/reference-style.csl" -o "/path/to/export-document.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd-citations --standalone +``` +To compile to PDF do: +``` +pandoc "path/to/myarticle.md" --citeproc --bibliography "/path/to/mycollection.bib" --csl "/path/to/reference-style.csl" -o "/path/to/export-document.pdf" +``` + +To compile to DOCX do: +``` +pandoc "path/to/myarticle.md" --citeproc --bibliography "/path/to/mycollection.bib" --csl "/path/to/reference-style.csl" -o "/path/to/export-document.docx" +``` +To compile to DOCX using a DOCX document as reference/template add the option: +``` +--reference-doc="path/to/reference-document.docx" +``` + +*Note: Conversions to *DOCX* format will use Footnotes, not Endnotes.* + +# Common errors + +- missing/wrong citation keys: [Pandoc][] will list all citation keys that were not found in the supplied `bib` file. Correct any potential citation key misspellings, or recompile your bibliography collection to include the missing citations. +- file not found: check file paths +- cannot write/open file: Pandoc is not able to overwrite files (such as PDF or DOCX) while they are open by other software. + + + +# Pandoc command reference + +[pandoc options manual]: https://pandoc.org/MANUAL.html#options + +See also [Pandoc demos](https://pandoc.org/demos.html), [Getting started with pandoc](https://pandoc.org/getting-started.html), and [pandoc options manual][]. + +A basic pandoc command example is: +``` +pandoc "path/to/input.txt" -o "path/to/output.docx" +``` +Additional options can be added to this command pattern to specify export parameters. + +Here is a brief list of some commonly used pandoc options (enclosing file paths inside quotation marks is optional): +- `-i "path/to/input/file.ext"` (input file, followed by path to file including file extension) +- `-o "/path/to/output/file.ext"` (output file, followed by path to file, including file extension) +- `-f` (output format, followed by option, see [pandoc options manual][]) +- `-t` (output format, followed by option, see [pandoc options manual][]) +- `-s`, `--standalone` (will render title, abstract, keywords, using data from front matter of the Markdown document) +- `-C`, `--citeproc` (option to render citations; will expect bibliography and csl files) +- `--bibliography "path/to/bibliography.bib"` +- `--csl "path/to/citation-style.csl"` (citation style file) +- `--atx-headers` (for common Markdown heading format) +- `--wrap=auto`|`none`|`preserve` (line wrapping options for plain text formats) +- `--strip-comments[=true|false]` (remove HTML comments) +- `--no-highlight` (Disables syntax highlighting for code blocks and inlines) + +