166 lines
8.5 KiB
Markdown
166 lines
8.5 KiB
Markdown
---
|
||
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  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 ).
|
||
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:
|
||
|
||
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):
|
||
|
||
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 "path/to/myarticle.md" --citeproc --bibliography "C:\Users\cmilt\Nextcloud\Aalto-NC\Publications\2301 DiGRA\bib\digraNN2.bib" --csl "C:\Users\cmilt\Nextcloud\Aalto-NC\Publications\2301 DiGRA\csl\chicago-author-date-3.csl" -o "C:\Users\cmilt\gdj-temp\mdexport\exp.md" --atx-headers --strip-comments --wrap=preserve -t markdown_mmd-citations --standalone
|
||
```
|
||
-->
|
||
|
||
# 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)
|
||
|
||
<!--
|
||
- `--metadata-file=`_FILE_
|
||
- `--markdown-headings=setext`|`atx`
|
||
- `--template=`_FILE_|_URL_
|
||
-->
|