Skip to content

Latest commit

 

History

History
232 lines (173 loc) · 15.5 KB

USAGE.md

File metadata and controls

232 lines (173 loc) · 15.5 KB

Manubot usage guidelines

This repository uses Manubot to automatically produce a manuscript from the source in the content directory.

Manubot markdown

Manuscript text should be written in markdown files located in the content directory. Markdown files are identified by their .md extension and ordered according to their two-digit prefix (e.g. 01., 02., … 99.).

For basic formatting, check out the CommonMark Help page for an introduction to the formatting options provided by standard markdown. In addition, Manubot supports an extended version of markdown, tailored for scholarly writing, which includes Pandoc's Markdown and the extensions discussed below.

Within a paragraph in markdown, single newlines are interpreted as whitespace (same as a space). A paragraph's source does not need to contain newlines. However, "one paragraph per line" makes the git diff less precise, leading to less granular review commenting, and makes conflicts more likely. Therefore, we recommend using semantic linefeeds — newlines between sentences. We have found that "one sentence per line" is preferable to "word wrap" or "one paragraph per line".

Tables

Manubot supports markdown tables.

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| value_a | 1 | 47 |
| value_b | 2 | 56 |

Table: Caption for this example table. {#tbl:example-id}

Support for table numbering and citation is provided by pandoc-tablenos. Above, {#tbl:example-id} sets the table ID, which creates an HTML anchor and allows citing the table like @tbl:example-id. For easy creation of markdown tables, check out the Tables Generator webapp.

Figures

Figures can be included with the following markdown:

![Caption for the example figure.](url_or_path_to_figure){#fig:example-id}

Support for figure numbering and citation is provided by pandoc-fignos. This figure can be cited in the text using @fig:example-id. In context, a figure citation may look like: Figure {@fig:example-id}B shows ….

For images created by the manuscript authors that are hosted elsewhere on GitHub, we recommend using a versioned GitHub URL to embed figures, thereby preserving exact image provenance. When embedding SVG images hosted on GitHub, it's necessary to append ?sanitize=true to the raw.githubusercontent.com URL. For example:

https://raw.githubusercontent.com/greenelab/scihub/572d6947cb958e797d1a07fdb273157ad9154273/figure/citescore.svg?sanitize=true

Figures placed in the content/images directory can be embedded using their relative path. For example, we embed an ORCID icon inline using:

![ORCID icon](images/orcid.svg){height="13px"}

The bracketed text following the image declaration is interpreted by Pandoc's link_attributes extension. For example, the following will override the figure number to be "S1" and set the image width to 5 inches:

{#fig:supplement tag="S1" width="5in"}

We recommend always specifying the width of SVG images (even if just width="100%"), since otherwise SVGs may not render properly in the WeasyPrint PDF export.

Citations

Manubot supports Pandoc citations via pandoc-citeproc. However, Manubot performs automated citation processing and metadata retrieval on in-text citations. Therefore, citations must be of the following form: @source:identifier, where source is one of the options described below. When choosing which source to use for a citation, we recommend the following order:

  1. DOI (Digital Object Identifier), cite like @doi:10.15363/thinklab.4. Shortened versions of DOIs can be created at shortdoi.org. shortDOIs begin with 10/ rather than 10. and can also be cited. For example, Manubot will expand @doi:10/993 to the DOI above. We suggest using shortDOIs to cite DOIs containing forbidden characters, such as ( or ).
  2. PubMed Central ID, cite like @pmcid:PMC4497619.
  3. PubMed ID, cite like @pmid:26158728.
  4. arXiv ID, cite like @arxiv:1508.06576v2.
  5. ISBN (International Standard Book Number), cite like @isbn:9781339919881.
  6. URL / webpage, cite like @url:https://nyti.ms/1QUgAt1.
  7. Wikidata Items, cite like @wikidata:Q50051684. Note that anyone can edit or add records on Wikidata, so users are encouraged to contribute metadata for hard-to-cite works to Wikidata as an alternative to using a raw citation.
  8. For references that do not have any of the persistent identifiers above, use a raw citation like @raw:old-manuscript. Metadata for raw citations must be provided manually.

Cite multiple items at once like:

Here is a sentence with several citations [@doi:10.15363/thinklab.4; @pmid:26158728; @arxiv:1508.06576; @isbn:9780394603988].

Note that multiple citations must be semicolon separated. Be careful not to cite the same study using identifiers from multiple sources. For example, the following citations all refer to the same study, but will be treated as separate references: [@doi:10.7717/peerj.705; @pmcid:PMC4304851; @pmid:25648772].

Citation tags

The system also supports citation tags, which are recommended for the following applications:

  1. A citation's identifier contains forbidden characters, such as ; or =, or ends with a non-alphanumeric character other than /. In these instances, you must use a tag.
  2. A single reference is cited many times. Therefore, it might make sense to define a tag, so if the citation updates (e.g. a newer version becomes available), only a single change is required.

Tags should be defined in content/citation-tags.tsv. If citation-tags.tsv defines the tag study-x, then this study can be cited like @tag:study-x.

Reference metadata

Manubot stores the bibliographic details for references (the set of all cited works) as CSL JSON (Citation Style Language Items). For all citation sources besides raw, Manubot automatically generates CSL JSON. In some cases, automatic metadata retrieval fails or provides incorrect or incomplete information. Errors are most common for url references. Therefore, Manubot supports user-provided metadata, which we refer to as "manual references". When a manual reference is provided, Manubot uses the supplied metadata and does not attempt to generate it.

Manubot searches the content directory for files that match the glob pattern manual-references*.* and expects that these files contain manual references. content/manual-references.json is the default file to specify custom CSL JSON metadata. Manual references are matched to citations using their "id" field. For example, to manually specify the metadata for the citation @url:https://github.com/manubot/rootstock, add a CSL JSON Item to manual-references.json that contains the following excerpt:

"id": "url:https://github.com/manubot/rootstock",

The metadata for raw citations must be provided in a manual reference file (e.g. manual-references.json) or an error will occur. For example, to cite @raw:private-message in a manuscript, a corresponding CSL JSON Item is required, such as:

{
  "id": "raw:private-message",
  "type": "personal_communication",
  "title": "Personal communication with Doctor X"
}

All manual references must provide values for the "id" and "type" fields. For guidance on what CSL JSON should be like for different document types, refer to these examples.

Manubot offers some support for other bibliographic metadata formats besides CSL JSON, by delegating conversion to the pandoc-citeproc --bib2json utility. Formats are inferred from filename extensions. So, for example, to provide metadata for @url:https://github.com/manubot/rootstock in BibTeX format, create the file content/manual-references.bib and create an item whose definition starts with the excerpt:

@misc{url:https://github.com/manubot/rootstock,

Processed reference metadata in CSL JSON format, either generated by Manubot or specified via manual references, is exported to references.json. This file is located in the output branch on GitHub or in the output subdirectory of local builds. The "id" field in references.json and in the final manuscript uses a shortened ID that is derived from the original ID. For debugging information, see citations.tsv, which shows citation identifiers as they progress through the processing pipeline. In order to freeze all references, rather than have Manubot regenerate them during future builds, copy the references.json output file to content with a filename matching the manual-references*.json pattern. One tip is to embed the date references.json was generated into the frozen manual reference filename, like content/manual-references-2019-06-21.json.

Manuscript metadata

content/metadata.yaml contains manuscript metadata that gets passed through to Pandoc, via a yaml_metadata_block. metadata.yaml should contain the manuscript title, authors list, keywords, and lang (language tag). Additional metadata, such as date, will automatically be created by the Manubot. Manubot uses the timezone specified in build.sh for setting the manuscript's date. For example, setting the TZ environment variable to Etc/UTC directs the Manubot to use Coordinated Universal Time.

We recommend authors add themselves to metadata.yaml via pull request (when requested by a maintainer), thereby signaling that they've read and approved the manuscript. The following YAML shows the supported key–value pairs for an author:

github: dhimmel  # strongly suggested
name: Daniel S. Himmelstein  # mandatory
initials: DSH  # strongly suggested
orcid: 0000-0002-3012-7446  # mandatory
twitter: dhimmel  # optional
email: [email protected]  # suggested
affiliations:  # as a list, strongly suggested
  - Department of Systems Pharmacology and Translational Therapeutics, University of Pennsylvania
  - Department of Biological & Medical Informatics, University of California, San Francisco
funders: GBMF4552  # optional

Note that affiliations should be a list to allow for multiple affiliations per author.

Manubot feedback

If you experience any issues with the Manubot or would like to contribute to its source code, please visit manubot/manubot or manubot/rootstock.

Examples

For additional examples, check out existing manuscripts that use the Manubot (some of which are still in progress):

If you are using the Manubot, feel free to submit a pull request to add your manuscript to the list above.

Citing Manubot

To cite the Manubot project or for more information on its design and history, see @doi:10.1371/journal.pcbi.1007128:

Open collaborative writing with Manubot
Daniel S. Himmelstein, Vincent Rubinetti, David R. Slochower, Dongbo Hu, Venkat S. Malladi, Casey S. Greene, Anthony Gitter
PLOS Computational Biology (2019-06-24) https://doi.org/c7np
DOI: 10.1371/journal.pcbi.1007128 · PMID: 31233491

The Manubot version of this manuscript is available at https://greenelab.github.io/meta-review/.

Acknowledgments

We would like to thank the contributors and funders whose support makes the Manubot project possible. Specifically, Manubot development has been financially supported by: