pubthis/README.Rmd at main · milanwiedemann/pubthis · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
---
output:
  github_document:
    html_preview: false
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

# pubthis

Render and publish Quarto manuscripts to Google Drive.
Fixes figure formatting issues that occur when converting `.qmd` files to Google Docs.
Keeps everyone working on the manuscript pointed to the same shared Google Doc.

**Suggested workflow**: write in Quarto, publish to Google Drive, get comments from collaborators, update the Quarto file, and repeat.
Changes do not sync back from Google Docs to Quarto.
The Quarto file remains the source of truth.
This lets collaborators comment and suggest changes in Google Docs.
The lead researcher then reviews the suggestions and manually transfers accepted changes back into the Quarto file.

## Installation

```r
# install.packages("pak")
pak::pak("milanwiedemann/pubthis")
```

To run the publishing workflow from the terminal you also need to install [just](https://github.com/casey/just) to run the just recipes.

## Getting started

### 1. Set up your project

Run once per project to add the required files:

```{r, eval = FALSE}
pubthis::use_publish_workflow()
```

This adds:

- `publish/reference.docx`: Word template for consistent styles
- `publish/docx-format.lua`: Lua filter that fixes figures in Google Docs
- `justfile`: task runner with `publish`, `open`, and `auth-gdrive` commands

`pubthis::publish()` applies the reference document and Lua filter automatically — no changes to your `.qmd` YAML are needed.
If you also render with plain `quarto render` and want the same Word styles, set `reference-doc: ../publish/reference.docx` under `format: docx:` in your `.qmd` YAML (adjust the relative path to where your manuscript lives).

### 2. Authenticate

Run once in an interactive R session to cache your Google Drive credentials.
From terminal using just (prints the commands to run):

```sh
just auth-gdrive
```

Or from R console:

```{r, eval = FALSE}
googledrive::drive_auth()
```

### 3. Publish

From terminal using just:

```sh
# Render and upload to Google Drive as Google Doc
just publish manuscripts/paper.qmd
# Open the published Google Doc in the browser
just open manuscripts/paper.qmd
```

Or from R console:

```{r, eval = FALSE}
pubthis::publish("manuscripts/paper.qmd")
pubthis::open_published("manuscripts/paper.qmd")
```

## Tracking the Google Doc

pubthis uses a `_publish.yml` file next to your `.qmd` to remember which Google Doc to update.
This is the same publish-record file `quarto publish` itself uses, so a `gdrive` entry lives alongside any `posit-connect-cloud` (or other provider) entry for the same file without disturbing it.
Commit this file so everyone on the project opens the same doc.
There are two ways to set this up:

1. Let pubthis create a new doc: On first publish, a new Google Doc is created and a `gdrive` entry is added to `_publish.yml` automatically. Every subsequent `publish` call updates that same doc in place.
1. Use an existing doc: If a shared doc already exists, add an entry to `_publish.yml` manually and paste in the doc ID (the long string between `/d/` and `/edit` in the doc URL)

```yaml
- source: paper.qmd
  gdrive:
    - id: <paste-google-doc-id-here>
```

Every subsequent `publish` call will update that doc in place.

## Related packages

- [trackdown](https://claudiozandonella.github.io/trackdown/)
- [officedown](https://davidgohel.github.io/officedown/)
- [officer](https://davidgohel.github.io/officer/)
- [redoc](https://github.com/noamross/redoc)