103 lines
4.7 KiB
Markdown
103 lines
4.7 KiB
Markdown
# ScientificManuscriptTemplate
|
|
|
|
A multi-project Quarto template for a manuscript, a research report, and supplements, sharing one set of resources (bibliography, CSL style, author/affiliation data, reference docx) and rendered via [Task](https://taskfile.dev).
|
|
|
|
|
|
## Requirements
|
|
|
|
- [Quarto](https://quarto.org)
|
|
- [Task](https://taskfile.dev)
|
|
- Python 3 (used for zipping/cleaning)
|
|
|
|
Make sure that Quarto, Task and Python are on your PATH.
|
|
|
|
## How to use
|
|
|
|
Clone the repo and edit `*.qmd` files, update author information in `resources/author_profiles/_quarto-default.yml` include references in `resources/references.bib` and render all projects using `task finalize`.
|
|
|
|
In any arch-based Linux distro, run `go-task finalize` instead.
|
|
|
|
More on how to include more detail in the front matter can be found in the official [quarto manual](https://quarto.org/docs/authoring/front-matter.html). Their quick introduction into [Markdown Basics](https://quarto.org/docs/authoring/markdown-basics.html) is also worth reading.
|
|
|
|
## Project layout
|
|
|
|
Each of `Manuscript/`, `ResearchReport/`, and `Supplements/` is its own Quarto project with its own `_quarto.yml`, `index.qmd`, `data/`, and `figures/` folders.
|
|
|
|
```
|
|
ScientificManuscriptTemplate/
|
|
├── Manuscript/ ← the paper itself
|
|
├── ResearchReport/ ← longer-form report
|
|
├── Supplements/ ← supplementary materialss
|
|
├── resources/ ← shared across all three projects
|
|
│ ├── references.bib ← biblatex references
|
|
│ ├── apa7.csl ← citation style, grab from https://www.zotero.org/styles/
|
|
│ ├── custom-reference-doc.docx ← docx template
|
|
│ └── author_profiles/
|
|
│ ├── _quarto-default.yml ← real author/affiliation metadata
|
|
│ └── _quarto-anonymized.yml ← anonymized-profile metadata
|
|
├── Taskfile.yml ← run commands from here for the whole project
|
|
└── finalized/ ← created by `task finalize`, date-stamped output
|
|
```
|
|
|
|
## Writing content
|
|
|
|
Edit the `.qmd` file(s) in whichever project you're working on (e.g. `Manuscript/index.qmd`). Put source data in that project's `data/` folder and images/plots in `figures/`. These are per-project, not shared.
|
|
|
|
Shared resources live once in `resources/` and are referenced via relative paths from each project's `_quarto.yml` (bibliography, CSL, reference docx, author metadata) - edit them there, not inside an individual project folder, so all three projects stay in sync.
|
|
|
|
## Authors and affiliations
|
|
|
|
Real author names and affiliations are defined once in `resources/author_profiles/_quarto-default.yml`. The anonymized counterpart lives in `_quarto-anonymized.yml` in the same older. Update uthor info there. It's picked up automatically by every project.
|
|
|
|
## Rendering
|
|
|
|
Each project has its own profile pair - `default` (real author info) and `anonymized` (for blind peer review) - selected via Quarto's `--profile` flag, which the Task commands below already handle for you.
|
|
|
|
**Render one project**, from inside that project's folder:
|
|
|
|
```
|
|
cd Manuscript
|
|
task render # default profile, all formats
|
|
task render:anonymized # anonymized profile, all formats
|
|
task render:html # single format, default profile
|
|
task render:docx
|
|
task render:pdf
|
|
task render:jats
|
|
```
|
|
|
|
**Or run any project's task from the repo root**, using its namespace:
|
|
|
|
```
|
|
task manuscript:render
|
|
task researchreport:render:anonymized
|
|
task supplements:render:docx
|
|
```
|
|
|
|
**Render everything at once**, from the repo root:
|
|
|
|
```
|
|
task render:all # all three projects, default profile
|
|
task render:all:anonymized # all three projects, anonymized profile
|
|
```
|
|
|
|
## Packaging and finalizing
|
|
|
|
```
|
|
task manuscript:package # zip Manuscript's default output
|
|
task manuscript:package:data # zip Manuscript/data into data.zip
|
|
task package:all # package every project, both profiles, plus data
|
|
task finalize # render everything, package everything,
|
|
# collect it all into finalized/<today's date>/
|
|
```
|
|
|
|
`task finalize` is the one command to run before submitting: it renders both profiles for all three projects, zips each project's output, and copies every zip into a fresh `finalized/YYYY-MM-DD/` folder so you have a clean, dated record of exactly what was submitted.
|
|
|
|
## Cleaning up
|
|
|
|
> [!WARNING]
|
|
> Be careful using this: the command also cleans caches, meaning that all computations will have to be re-evaluated.
|
|
|
|
```
|
|
task manuscript:clean # remove Manuscript's _output, .quarto, and stray cache folders
|
|
task clean:all # same, for all three projects
|
|
``` |