Formatting your Google Doc

The Stacks reads two kinds of formatting from your Google Doc:

• Native Google Docs formatting such as headings, bold, italic, lists, tables, and links.

• Directives, which are text markers you type into the doc to create richer blocks like figures and callouts.

To see these features in published work, see Things to try.

Before you import¶

Share every Drive file you reference, such as images and videos, the same way as your doc (see Importing from Google Docs). If even one file is private, the import fails.

Accept or reject all suggested edits, because suggestions and comments aren’t imported.

What carries over¶

Semantic formatting is kept: headings, bold, italic, superscript, subscript, links, lists, tables, and paragraph alignment. Use Google Docs’ built-in paragraph styles for headings.

Visual styling is dropped: highlight, font color, fonts and sizes, underline, strikethrough, line spacing, and page breaks. Footnotes, text boxes, and drawings are dropped too, so export drawings as images and add them as media.

How directives work¶

A directive is a fenced block you type as plain text in your doc:

:::directive-name
:attribute: value
:another-attribute: value
Free-form content, like a caption.
:::

• Put the opener (:::media) and closer (:::) on their own paragraphs, with nothing else on the line, not even a leading space.

• Put each attribute on its own paragraph, formatted :key: value.

• Use a real new paragraph (Enter), not a soft line break (Shift+Enter).

• Don’t use Google Docs’ “Code block” element for directives. Type the characters as normal text.

Styling directive text in a monospace font with a grey background makes it easier to spot, and doesn’t affect the import.

Document structure¶

A publication is laid out as title, subtitle, abstract, body sections, and then acknowledgments.

• Title: the first paragraph, using the “Title” paragraph style. Only one.

• Subtitle: optional, directly after the title, 280 characters or fewer.

• Abstract: can span multiple paragraphs.

• Sections: Heading 1 for top-level sections, Heading 2 and below for subsections. Only H1 and H2 appear in the table of contents.

:::subtitle
One sentence on the impact of this work.
:::

:::abstract
First paragraph of the abstract.

Second paragraph of the abstract.
:::

Acknowledgments and competing interests each go in a bordered block. The heading inside must be Heading 4.

:::bordered
:internal: acknowledgments
#### Acknowledgments
Thank collaborators, funders, and contributors here.
:::

:::bordered
:internal: competing interests
#### Competing interests
Declare any conflicts of interest here.
:::

Figures and other media¶

The :::media directive handles images, videos, audio, embeds, and file downloads. The :type: attribute picks which one.

:::media
:type: image
:id: growth-curves
:src: https://drive.google.com/file/d/1AbcDefGhiJklMnoPqr/view?usp=sharing
:width: 100%
:align: center
:alt: Nine growth curves arranged in a grid, one per temperature.
**Growth rate varies with temperature across all 84 isolates.**
Each panel shows OD600 over time for one temperature condition.
:::

Attributes¶

Store figures at their best resolution.

Supported formats:

• Images: JPEG, PNG, GIF, SVG, WEBP

• Video: AVI, MOV, MP4

• Audio: MP4, WAV, OGG, M4A

Captions and numbering¶

• Write the caption after the last attribute and before the closing :::, with no attribute prefix.

• Bold the first sentence as the caption title.

• Figures are numbered automatically (“Figure 1”, “Video 1”) in document order. Don’t number them yourself.

Alignment¶

left and right float the figure and wrap text around it. Use them only for narrow figures, roughly 65% width or less. Wide figures won’t float on The Stacks even if you set left or right.

For YouTube videos, use the embed URL, like https://www.youtube.com/embed/0peLwtqQX7I, not the watch?v= URL.

Tables¶

Use a native Google Docs table (Insert → Table).

• Make every cell in a row bold to format it as a header row.

• Bold, italic, links, and super/subscript work inside cells.

• Column alignment set in Google Docs is not kept.

To caption and number a table, add a :::meta block right after it:

:::meta
:id: strain-list
**Wild strains used in this study.**
Twenty representative strains from the full panel.
:::

Referencing figures and tables¶

Type :ref{#id} in your text, using the :id: of the figure or table:

We summarize the trend in :ref{#growth-curves}.

• The # is required.

• Type it as plain text, not as a Google Docs link.

• The Stacks replaces it with the right number, like “Figure 1”.

Note: ref is also used for citations. See Citations.

Math¶

Write math as LaTeX. Use $...$ for inline math and $$ fences on their own paragraphs for block math:

We normalized readings as $\log(1 + x)$.

$$
\mu_{\text{max}} = \frac{\ln(\text{OD}_{t_2}) - \ln(\text{OD}_{t_1})}{t_2 - t_1}
$$

Don’t put bold or italic formatting inside the dollar signs.

Code¶

Wrap inline code in single backticks. It’s fine if Google Docs turns it into green monospace text.

For code blocks, use triple-backtick fences with a language name. Paste the code with Paste without formatting (⌘+Shift+V or Ctrl+Shift+V), or The Stacks won’t recognize it.

```r
library(tidyverse)
growth_data |> group_by(strain_id, temperature)
```

See the list of supported languages.

Callouts¶

:::callout
**Data and code** for this pub are in [this repository](https://github.com/example/repo).
:::

Callouts can contain paragraphs, lists, links, and media blocks.

Collapsible content¶

Use :::details to hide content behind a click-to-expand toggle. An optional :::summary right after the opener stays visible when it’s collapsed.

:::details
:::summary
## Bonus data: one strain shows unusual cold tolerance
:::
This content is hidden until the reader expands it.
:::

• Add :open: true under :::details to expand it by default.

• Use only one :::summary per :::details, and don’t nest it inside another directive.

Links within your doc¶

• To a heading: select your text, press ⌘+K, and type the heading’s slug as the URL, like #our-results. The slug is the heading text in lowercase with hyphens. Don’t use the “Headings and bookmarks” picker for headings.

• To anywhere else: add a bookmark (Insert → Bookmark), then link to it with the “Headings and bookmarks” picker. The bookmark must be at the start of a paragraph and followed by plain text.

If you rename a heading, update any links to its old slug.

Web-only content¶

Wrap content in :::only to leave it out of the PDF export, for example a feedback poll:

:::only
:platform: web
:::media
:type: iframe
:src: https://example.typeform.com/to/feedback
:align: center
:width: 100%
:height: 550px
:::
:::

Don’t use this for interactive figures that are part of your argument. By default, The Stacks puts a screenshot of them in the PDF.

Small text¶

You can use HTML as an escape hatch to use styles that are not covered by standard Markdown or the formatting directives. For example, you can get small text with HTML.

<span class="text-body-20">Small text content.</span>

Citations¶

See Citations.