git clone https://github.com/mitchellmcm27/pandoc-manuscript-starter your-paper

This is a starter kit for writing manuscripts in Markdown using Pandoc. Any text editor can be used to generate manuscripts, but a VS Code workspace is provided here. This setup splits the process of creating a manuscript into two tasks:

For writing, we provide

• A flat directory for organizing your manuscript files. All author content is placed in the root directory, while supplementary files are in subfolders.
• The ability to write text fully in Markdown, which is simpler to read and write than LaTeX.
• Bibliography integration with BibTeX, automating reference citation and formatting.
• Citation autocomplete (VS Code package Pandoc Citer).
• The ability to customize the formatting of the bibliography, by copying a .csl file into the styles folder.

For generating the final manuscript file (building)

• High quality output in pdf (or docx, or others) with Pandoc.
• Build locally with VS Code and the vscode-pandoc package (requires installing Pandoc, LaTeX, and any other dependencies on your machine).
• Automatically build pdfs using Github Actions (see below).

Extend the project in any number of ways to integrate the build system of your choice.

Note that you can build pdfs from Markdown using LaTeX and pandoc on your computer, but this requires both to be installed and set up properly (along with any other packages or pandoc filters). Getting the right variables on your PATH can be a hassle, and a LaTeX distribution (with packages) can take up significant hard disk space. Additionally, it's nice to be able to write in Markdown anywhere, from any machine, even in the browser, with pdf and docx generated on commits. This is why the automatic builds with Travis are nice.

The included VS Code workspace settings assume you have LaTeX, pandoc, and pandoc-crossref installed and set up, but this can be modified (see .vscode/settings.json).

Essential VS Code packages

• vscode-pandoc - run pandoc locally to build pdf, docx, etc.
• Pandoc Citer - autocomplete for Markdown references (eg @McMillan2017)
• Markdown All in One - kb shortcuts, autocomplete, clickable links, etc.

These are recommended in the VS Code workspace settings.

Other VS Code packages

• LaTeX Workshop - in case you need to drop down into LaTeX syntax
• Code Spell Checker

Automatic citation styles and reference formatting

Thousands of bibliography and citation styles are publicly available as .csl files. Changing the style involves downloaing one of these into the styles folder and changing the --csl pandoc argument (or updating the csl field in the YAML header of the document) to this new file. CSL files can be found at the official Citation Style Language repository.

Automatic builds with Github actions

If you fork this repository, Github will take care of generating a pdf from the manuscript.md file whenever you push changes to any branch. See the .github/workflows/main.yml file and customize it as needed.

Use GitHub's Codespaces as a text editor

You can edit the manuscript, save changes, and automatically generate a pdf, all within your web browser using GitHub's Codepsaces. In your GitHub repository, press the . key or swap .com with .dev in the URL to go directly to a VS Code environment in your browser. Edit the manuscript.md file, or any other file, to your liking. Push the changes to GitHub, and come back to the Actions tab to view the generated pdf.