Using Manuscripts

Overview

Manuscripts are a type of Quarto project that allow you to write scholarly articles where computational notebooks are both the source of the article, and part of the published record.

If you are new to Quarto manuscripts, start with the Manuscript Tutorial.

On this page, you can learn how to:

  • Create a manuscript project
  • Control the manuscript output with options in _quarto.yml
  • Add a journal template

Creating a Manuscript Project

To identify a project as a manuscript specify type: manuscript in your _quarto.yml configuration file:

_quarto.yml
project: 
  type: manuscript

Then, author your article content in either a Jupyter Notebook called index.ipynb or a Quarto document called index.qmd.

You can control many manuscript options with the manuscript key in your configuration file. For instance, you can specify a file other than index.* for your article source using the article key, e.g.:

_quarto.yml
manuscript:
  article: earthquakes.qmd

If you would rather start with some template content, you can create a new manuscript project from the command line with:

Terminal
quarto create project manuscript

Including Notebooks

Any notebook files (.qmd or .ipynb) that are included in your project directory will become part of your manuscript. These notebooks will be rendered to an HTML notebook view, and will be linked from your manuscript webpage under “Notebooks”.

External Notebooks

To provide links to notebooks that are hosted elsewhere, add the url option:

_quarto.yml
manuscript:
  notebooks:
    - notebook: index.ipynb
      title: Binder Jupyter Lab Demo
      url: http://mybinder.org/v2/gh/binder-examples/jupyterlab/master?urlpath=lab/tree/index.ipynb

If you want Quarto to produce an HTML notebook view from your notebook source, but you would like to provide a specific version for download, add the download-url option:

_quarto.yml
manuscript:
  notebooks:
    - notebook: notebooks/data-screening.ipynb
      title: Data Processing
      download-url: notebooks/data-screening-raw.ipynb

Including Other Resources

Quarto will attempt to include resources needed to render your notebooks to HTML on the manuscript website. However, you can also explicitly include resources using resources. For example, to include a data file you’ve put in data/earthquakes.csv you would specify:

_quarto.yml
manuscript:
  resources:
    - data/earthquakes.csv

This ensures readers can access your data at: {manuscript-url}/data/earthquakes.csv.

MECA Bundle

One of the formats a manuscript project can produce is a Manuscript Exchange Common Approach (MECA) bundle. This bundle is a standardized way to transport your manuscript and its resources, including computational notebooks.

A MECA bundle is produced if the jats format is listed as an output format for your article:

_quarto.yml
format:
  html: default
  jats: default

Or, you can explicitly set meca-bundle to true in the manuscript options:

_quarto.yml
manuscript:
  meca-bundle: true

By default the MECA bundle is named after your article file, e.g. index-meca.zip, but you can also use meca-bundle to provide a file name:

_quarto.yml
manuscript:
  meca-bundle: "bundle.zip"

Manuscript URL

Links to your notebooks in non-HTML formats are constructed using the URL of your manuscript website. If your manuscript is published to GitHub Pages, Quarto will detect and set the URL for you. However, if you publish to a different host, or the automatic detection isn’t working, you can set the URL explicitly with manuscript-url:

_quarto.yml
manuscript:
  manuscript-url: www.posit.co

Using Binder

Binder allows you to provide readers with a link that restores your computing environment so they can interact with your manuscript notebooks in a cloud computing environment.

Quarto can help you configure your manuscript to use Binder. Read more at Using Binder.

Customizing Pages

The article page and notebook views on your manuscript site are HTML pages, and can be customized using options for the html format. A full list of options is available at HTML Options.

Theme

For example, you can change the visual styling of your page with the theme option by providing an existing theme name:

_quarto.yml
format:
  html: 
    theme: solar

You can read more at HTML Theming.

Commenting

Quarto also integrates with three tools to allow commenting on your manuscript site. To enable commenting, use the comments option to the html format. For example, to enable Hypothes.is comments, you just need to add hypothesis: true:

_quarto.yml
format:
  html: 
    comments:
      hypothesis: true

The other two tools available are Utterances and Giscus. You can read about setting them up at HTML Basics: Commenting.

Add a Journal Template

You can find a list of available journal formats on the Quarto Extensions: Journal Articles page. To use a journal format, e.g. the acs format, you’ll need to complete two steps:

  1. Install the appropriate journal format. You’ll most likely be installing in an existing project, so you’ll use the quarto install extension command, e.g.:

    Terminal
    quarto install extension quarto-journals/acs

    The extension identifier, quarto-journals/acs, is the GitHub user and repository for the extension. You’ll generally find this, and the exact installation command in the extension’s documentation.

  2. Add the format to your configuration file:

    _quarto.yml
    format:
      html: default
      docx: default
      jats: default
      acs-pdf: default

    The format will be the extension’s name (acs), followed by an existing Quarto format (-pdf).