Publish a single article repository

Use this configuration when one repository is one paper, for example a preprint, a report or a thesis chapter. This is how it behaves once set up:

• Every pull request to main builds a preview and runs the site’s checks. A comment on the pull request links to both and updates on each push.

• Every merge to main submits a new version of the same submission to your Curvenote site. With publish: true that version is published straight away.

Have your venue, kind and CURVENOTE_TOKEN secret ready, as described in Before you start. Or let your coding agent do the setup with the agent prompt.

Repository layout¶

my-paper/
├── .github/
│   └── workflows/
│       ├── curvenote-preview.yml   ← previews and checks on pull requests
│       └── curvenote-submit.yml    ← submits on merge to main
├── myst.yml                        ← project.id identifies the submission
├── index.md
└── figures/

myst.yml needs a project.id. By default the actions expect a UUID, which curvenote init generates:

version: 1
project:
  id: 3f2b8c1e-9a4d-4e6f-b7c2-1d5e8a9f0b34
  title: Soil moisture dynamics in semi-arid grasslands

1. Add the preview workflow¶

Create .github/workflows/curvenote-preview.yml:

name: Curvenote preview
on:
  pull_request:
    branches: ['main']
permissions:
  contents: read
  pull-requests: write
jobs:
  preview:
    uses: curvenote/actions/.github/workflows/draft.yml@v1
    with:
      venue: '<VENUE>'
      kind: '<KIND>'
    secrets:
      CURVENOTE: ${{ secrets.CURVENOTE_TOKEN }}
      GITHUB: ${{ secrets.GITHUB_TOKEN }}

pull-requests: write lets the workflow comment on the pull request. Add collection: '<COLLECTION>' under with: if you are not submitting to the site’s default collection.

2. Add the submit workflow¶

Create .github/workflows/curvenote-submit.yml:

name: Curvenote submit
on:
  push:
    branches: ['main']
permissions:
  contents: write
jobs:
  submit:
    uses: curvenote/actions/.github/workflows/submit.yml@v1
    with:
      venue: '<VENUE>'
      kind: '<KIND>'
      # publish: true
    secrets:
      CURVENOTE: ${{ secrets.CURVENOTE_TOKEN }}
      GITHUB: ${{ secrets.GITHUB_TOKEN }}

contents: write lets the workflow post its summary as a comment on the merged commit.

Without publish, each merge creates a new submission version that the site’s editors review and publish in Curvenote. To publish automatically, uncomment publish: true.

3. Try it¶

1. Commit both workflows on a branch and open a pull request. Within a few minutes a Curvenote Preview comment appears, with links to the build, the preview and the check results.

2. Push more commits; the same comment is updated.

3. Merge the pull request. The submit workflow runs on main and comments on the commit with the new submission version.

The merge that adds the submit workflow also submits your current content.

Options¶

These are the options most often needed in this configuration. The reference lists them all.

Article in a subfolder. If myst.yml is not at the repository root, set path in both workflows, e.g. path: manuscript. Only that folder is built.

Keeping a non-UUID ID. If your project.id is not a UUID, such as kerr-lab-ms-2026, don’t change it, especially if it has already been submitted. Instead, tell the actions to accept it:

      id-pattern-regex: '^kerr-lab-ms-2026$'

Pull requests from forks. GitHub withholds secrets from pull_request runs triggered by forks, so fork PRs get no preview. To preview them, switch the preview trigger to pull_request_target and gate it with a label that maintainers add after reviewing the change. See Multiple articles for what this implies.

on:
  pull_request_target:
    branches: ['main']
    types: [labeled, opened, synchronize, reopened]
# ...
    with:
      venue: '<VENUE>'
      kind: '<KIND>'
      label: draft

Stricter submissions. strict: true skips the submission when checks fail.

PDF fonts. If your PDF export uses Typst and needs fonts beyond Noto, use fonts to list the Debian font packages to install, e.g. fonts: 'fonts-noto-core fonts-noto-color-emoji'.