{"id":21206700,"url":"https://github.com/oncomouse/dhsi-pandoc2018","last_synced_at":"2026-02-08T19:32:38.021Z","repository":{"id":149627976,"uuid":"137034840","full_name":"oncomouse/dhsi-pandoc2018","owner":"oncomouse","description":null,"archived":false,"fork":false,"pushed_at":"2018-07-28T15:17:21.000Z","size":156,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-07-18T19:22:13.052Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oncomouse.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-12T07:37:04.000Z","updated_at":"2019-07-18T07:40:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"aafef487-525e-46bc-ad73-860b407229c0","html_url":"https://github.com/oncomouse/dhsi-pandoc2018","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/oncomouse/dhsi-pandoc2018","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncomouse%2Fdhsi-pandoc2018","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncomouse%2Fdhsi-pandoc2018/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncomouse%2Fdhsi-pandoc2018/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncomouse%2Fdhsi-pandoc2018/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oncomouse","download_url":"https://codeload.github.com/oncomouse/dhsi-pandoc2018/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncomouse%2Fdhsi-pandoc2018/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29240674,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-08T18:06:38.086Z","status":"ssl_error","status_checked_at":"2026-02-08T18:06:09.124Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-20T20:56:36.036Z","updated_at":"2026-02-08T19:32:37.993Z","avatar_url":"https://github.com/oncomouse.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Writing Made Plain\n\nThis tutorial page is designed to get you writing in Markdown,  exporting to MS Word, and fully automating the management of your citations.\n\nAdvantages of writing this way:\n\n* Writing anywhere\n    * Markdown is an open format that, at the end of the day, is just plain text. You can dictate on your phone and paste it into your MS without any formatting problems.\n* Maintainability\n    * As an open format, the Markdown document you write today will be just as readable in a decade. No worrying about updating your MS to new versions of a proprietary word processor!\n* Automatically generate works cited and references\n    * Including the ability to switch citation styles without reformatting!\n* Meaningful track changes on Dropbox or GitHub\n    * Because Markdown is plain text, the changes tracked on your favorite offsite backup will track word-by-word edits.\n\n## Agenda\n\n1. What Software?\n1. What is Markdown?\n1. Installing Everything\n1. Build Your Document\n1. Advanced Pandoc\n1. Advanced Project Organization\n\n## Software We Will Be Using\n\n1. **Atom** – An extensible, FOSS text editor that has excellent Pandoc support\n1. **Pandoc** – A document converter that, amongst many other things, converts Markdown to MS Word, HTML, and PDF\n1. **Zotero** – A reference management tool for organizing and collecting references\n1. **Zotero Better BibTeX** – A Zotero plugin that automatically exports the plain text bibliography file used by Pandoc and Atom\n\n## Markdown\n\n~~~markdown\n# Header Level 1\n\n## Header Level 2\n\n### etc.\n\nThis is a basic paragraph. It has two line breaks at the end to indicate that it is done. Here's a [link](http://google.com).\n\nHere's **some bold text**. Here's *some italics text*.\n\n* Here's an unordered list\n* With\n* Four\n* Entries\n\n1. We can also\n1. Number\n1. Our\n1. Lists\n\n\u003e Hello, this is a block quote.\n\u003e\n\u003e It can continue for multiple paragraphs.\n\n![A Blue Rectangle](images/blue.png)\n\nI have a footnote.[^fn1] I have a footnote.[^fn1] I also have a footnote.^[But, I don't need an ID.]\n\n[^fn1]: I am a footnote. My ID is unique.\n~~~\n\n`pandoc -s -f markdown+smart -o sample.pdf sample.md`\n\n## The Stack in Action\n\nThis is a much more complicated Markdown document:\n\n~~~markdown\n---\ntitle: \"Hello There\"\nbibliography: test.bib\ncsl: modern-language-association-7th-edition.csl\nauthor:\n  - Andrew Pilsch\n---\n\nHere's a citation [@lem_summa_2014, p. 24].\n\nHere's another [@bratton_stack_2016, p. 243].\n\nHere's a third [@colebrook_what_2016, p. 22].\n\n\u003e I'm a blockquote. [@bernal_world_2018, p. 147]\n\n~~~\n\nNew elements:\n\n* YAML metadata block\n* Citations!\n\n## Installation Overview\n\nTo setup our full writing Stack, we will need to:\n\n1. Install a FOSS Package Manager\n2. Install Git\n3. Install Pandoc\n4. Install CSL\n5. Install Atom\n6. Install Zotero\n7. Install Zotero Better BibTeX\n\n## Install a FOSS Package Manager\n\nThere is a world of command line, FOSS (Free and OpenSource Software) available, even for Windows. To make installing it easier, I ask you install a package manager: Home Brew for macOS, Scoop for Windows.\n\nNeed help with the command line? [Tracy Osborn's pamphlet is quite good](https://drive.google.com/file/d/1_2LTtR6f5bFCC5wjFZc9ILA7vmru7ShK/view?usp=sharing).\n\nAt a bare minimum, you should be able to move between directories (`cd`), list directory contents (`ls`), and create new directories (`mkdir`) for using pandoc.\n\n### macOS\n\nWe're installing [Home Brew](https://brew.sh/), an FOSS installer for macOS.\n\nOpen Terminal (\u003ckbd\u003e⌘\u003c/kbd\u003e+\u003ckbd\u003eSpace\u003c/kbd\u003e, then \"Terminal\" and \u003ckbd\u003e⏎\u003c/kbd\u003e OR /Applications/Utilities and double-click \"Terminal\"). In Terminal, paste the following: `/usr/bin/ruby -e \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)\"` and press \u003ckbd\u003e⏎\u003c/kbd\u003e.\n\n### Windows\n\nWe're installing [scoop](https://scoop.sh/), an FOSS installer for Windows.\n\nOpen Powershell (\u003ckbd\u003eWin\u003c/kbd\u003e+\u003ckbd\u003eR\u003c/kbd\u003e, then \"powershell\" and \u003ckbd\u003e⏎\u003c/kbd\u003e). In Powershell paste (right-click) the following: `iex (new-object net.webclient).downloadstring('https://get.scoop.sh')` and press \u003ckbd\u003e⏎\u003c/kbd\u003e.\n\n## Install Git\n\nGit is the command line tool that powers GitHub. We will use it to download some repositories.\n\n### Windows\n\nIn Powershell, run:\n\n* `scoop install git`\n\n### macOS\n\nIn Terminal, run:\n\n* `brew install git`\n\n## Install Pandoc (+ LaTeX for PDF)\n\nFor now, install Pandoc, if you're following along. I would suggest waiting to install LaTeX, as it is a very big download, especially for macOS.\n\nWaiting to install LaTeX is fine, as it is only used to convert to PDFs in Pandoc.\n\n### Windows\n\nRun the following in Powershell:\n\n* `scoop bucket add extras`\n* `scoop install pandoc`\n\nLater, for PDF support:\n\n* `scoop install latex`\n\n### macOS\n\nRun the following in Terminal:\n\n* `brew update`\n* `brew install pandoc`\n\nLater, for PDF support:\n\n* `brew tap phinze/cask`\n* `brew install brew-cask`\n* `brew cask install mactex`\n\n## Install CSL\n\nCSL (Citation Style Language) is an XML grammar that describes citation systems, including in-text / note references and works cited pages. Pandoc uses CSL to format your references.\n\n### Windows\n\nIn Powershell, run `git clone https://github.com/citation-style-language/styles \"$env:appdata\\csl\"`\n\n### macOS\n\nIn Terminal, run `git clone https://github.com/citation-style-language/styles $HOME/.csl`.\n\n## Install Atom\n\nTechnically you could use any text editor (even Notepad on Windows or Speech-to-text on your phone) to edit your Markdown documents, but I like Atom and it has some great support.\n\nDownload the installer from [https://atom.io/](https://atom.io/). There is one more step for Windows.\n\n### Windows Additional Step\n\nopen Powershell (\u003ckbd\u003eWin+R\u003c/kbd\u003e, type \"powershell\", and press \u003ckbd\u003eEnter\u003c/kbd\u003e). Copy the following command and paste it into the shell (you paste into Command Line by right clicking): `$env:path += \";$env:localappdata\\atom\\bin\"`. This will add the commands `apm` (for install Atom packages) and `atom` (for launching the editor from the command line) to your path. After testing that those commands work, run `[Environment]::SetEnvironmentVariable(\"Path\", $env:Path)` to finalize your changes for future sessions.\n\n### Install and Configure Packages\n\nOn your command line (Powershell for Windows; Terminal for macOS), copy and paste the following line: `apm install markdown-preview-plus markdown-writer language-pfm autocomplete-bibtex wordcount`. Press \u003ckbd\u003e⏎\u003c/kbd\u003e.\n\nWhen that finishes, go back to Atom. Bring up the command palette (\u003ckbd\u003e⌘\u003c/kbd\u003e+\u003ckbd\u003e⇧\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e on macOS; \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003e⇧\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e on Windows) and type \"installed\". Choose \"Setting View: View Installed Packages\" from the dropdown and press \u003ckbd\u003e⏎\u003c/kbd\u003e. In the \"Installed Packages\" tab that opens, search for \"gfm\" and find the package **\"language-gfm\"** in the results. Click the \"Disable\" button in that result card.\n\nYou may need to restart Atom at this point.\n\nAtom is *very* powerful and highly configurable. You may want to [change your theme](https://flight-manual.atom.io/using-atom/sections/atom-packages/#atom-themes) (as I have); you may also want to investigate what packages developers use when working with your favorite language (I have Python and JavaScript heavily customized as well).\n\nYou may also want to turn on [autosave](https://atom.io/packages/autosave) to automatically save your work as you edit it.\n\n* [List of Atom Themes](https://atom.io/themes)\n\n## Install Zotero\n\n### Windows and macOS\n\nDownload [Zotero](https://www.zotero.org/) at [https://www.zotero.org/download/](https://www.zotero.org/download/). Run the installer and install as you would normally.\n\n### Install Zotero Better BibTeX\n\nVisit [https://github.com/retorquere/zotero-better-bibtex/releases/latest](https://github.com/retorquere/zotero-better-bibtex/releases/latest) and click the link to a `.xpi` file.\n\nWhen that download finishes, open Zotero and:\n\n1. In the main menu go to Tools \u003e Add-ons\n1. Select 'Extensions'\n1. Click on the gear in the top-right corner and choose 'Install Add-on From File...'\n1. Choose .xpi that you've just downloaded, click 'Install'\nRestart Zotero\n\n## Configuring Zotero Better BibTeX and autocomplete-bibtex\n\nIn Zotero, right click on \"My Library\" and choose \"Export Library ...\" from the drop-down menu. From the \"Format\" dropdown menu, choose \"Better BibLaTeX\" and check the box next to \"Keep updated\". Save the file someplace permanent, \"Documents\" on macOS or \"My Documents\" on Windows,  and name it whatever you like.\n\nIn Atom, bring up the command palette (\u003ckbd\u003e⌘\u003c/kbd\u003e+\u003ckbd\u003e⇧\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e or \u003ckbd\u003eCtrl\u003c/kbd\u003e+\u003ckbd\u003e⇧\u003c/kbd\u003e+\u003ckbd\u003eP\u003c/kbd\u003e) and type \"installed\". Choose \"Setting View: View Installed Packages\" from the dropdown and press \u003ckbd\u003e⏎\u003c/kbd\u003e. In the \"Installed Packages\" tab that opens, search for \"autocomplete\" and find the package **\"autocomplete-bibtex\"** in the results. Click the \"Settings\" button in that result card.\n\nUnder the \"Settings\" heading, find the input field labelled \"Bibtex\". Type the file path for your exported library. For instance, if you saved it to \"Documents\" on macOS, type \"~/Documents/My Library.bib\" (assuming you didn't rename the file).\n\nNow, open a Markdown document and start typing a citation key (\"@\" + whatever); the pop-up menu will let you select the citation from your Zotero library to add to your document.\n\nIf you haven't added anything to Zotero yet, add something to your library. To make this easy, you will want to install \"Zotero Connector\" for your favorite web browser. This will let you push a button in the browser to import citations into your library. Visit [https://www.zotero.org/download/](https://www.zotero.org/download/) and install it. \n\nAs you add citations to your library, Zotero Better BibTeX will automatically export these new citations to the .bib file we just showed to our plugin. This happens because we remembered to check the \"Keep updated\" box when we were exporting a minute ago.\n\nThe only thing you have to remember is that Zotero has to be open when you want to import citations from the browser. Otherwise, everything should just work!\n\n## Build a Document\n\nWe are now ready to start editing our document in Atom. When it is time to compile it, we can run something like:\n\n`pandoc --filter=pandoc-citeproc -s -f markdown+smart -o test.pdf test.md`\n\nTo get different outputs, change the file extension on the -o switch (so, to .docx).\n\n**Note**: Unlike most of what we've done today, you have to run pandoc in the same directory as your Markdown files. Use the `cd` command (and remember that hitting the tab key will cause your command line to autocomplete file names for you) to change into the same directory as your files. Also remember when `cd`ing, that if your file path (which is the sequence of slashes (or backslashes) and folder names that makes up the entire route from the current directory to the desired one) has spaces in it, you can put a `\\` in front of the space to escape it or you can surround the whole file path in quotation marks (`\"`).\n\n## What Else Can We Do With Pandoc?\n\n### Change Citations at the Drop of a Hat!\n\nSo, your MS is now in chicago with endnotes. No problem. Browse or search the [Citation Style Language GitHub repo](https://github.com/citation-style-language/styles) to find the one you want.\n\nIn this case, the one we want is \"chicago-fullnote-bibliography-with-ibid.csl\". We can change our citations by changing the YAML front matter `csl` key to the new file. Then we recompile our document.\n\nThat's it!\n\n### Import Track Changes into Markdown\n\nReviewer #2 got you down? You can import track changes comments into a markdown document using the following:\n\n`pandoc --track-changes=all -f markdown+smart test.docx -o test-draft.md`\n\n**Very Important**: This document will not have citation information, so *do not* output to the original manuscript file. Create a new draft file.\n\n## How Would I Use this to Write a Book?\n\nI'm glad you asked that! Though this is outside the scope of this tutorial, I have created a GitHub repo for organizing and writing books using Pandoc Markdown. The repo is at: [https://github.com/oncomouse/rake-and-pandoc](https://github.com/oncomouse/rake-and-pandoc)\n\nYou will need to install the Ruby programming language and a few tools in order to get started.\n\n### Installing for Windows\n\nOpen Powershell again and run `scoop install ruby`.\n\n### Installing for macOS \n\nOpen Terminal again and run `brew install ruby`.\n\n### Downloading the Repo\n\nIn your command line, `cd` to where you would like to start your book. Run `git clone https://github.com/oncomouse/rake-and-pandoc` to clone the repo. You can rename that repo by running `mv rake-and-pandoc \"My Awesome Book\"` (with \"My Awesome Book\" (but not the quotes) replaced with your awesome book title).\n\nAlso, to clear out my repo's GitHub URL (and to eventually start your own), run `git remote rm origin`.\n\n### Configuring Ruby\n\nIn your command line (either Powershell or Terminal) `cd` into the directory you just created (either `cd rake-and-pandoc` or `cd \"Whatever Your Book is Called\"`). Run `gem install bundler`. Next, run `bundle install`.\n\nRead the `Readme.md` file for more information on how to use `rake` (which we just installed) to build parts or all of your MS.\n\n## Further Reading\n\n* [\"A Plain Text Workflow for Academic Writing with Atom\"](http://u.arizona.edu/~selisker/post/workflow/)\n* [\"Sustainable Authorship in Plain Text using Pandoc and Markdown\"](https://programminghistorian.org/en/lessons/sustainable-authorship-in-plain-text-using-pandoc-and-markdown)\n* [*The Plain Person’s Guide to Plain Text Social Science*](http://plain-text.co/)\n\nHappy Writing!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foncomouse%2Fdhsi-pandoc2018","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foncomouse%2Fdhsi-pandoc2018","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foncomouse%2Fdhsi-pandoc2018/lists"}