Update README.md
This commit is contained in:
+102
-102
@@ -1,103 +1,103 @@
|
|||||||
# ScientificManuscriptTemplate
|
# 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).
|
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
|
## Requirements
|
||||||
|
|
||||||
- [Quarto](https://quarto.org)
|
- [Quarto](https://quarto.org)
|
||||||
- [Task](https://taskfile.dev)
|
- [Task](https://taskfile.dev)
|
||||||
- Python 3 (used for zipping/cleaning)
|
- Python 3 (used for zipping/cleaning)
|
||||||
|
|
||||||
Make sure that Quarto, Task and Python are on your PATH.
|
Make sure that Quarto, Task and Python are on your PATH.
|
||||||
|
|
||||||
## How to use
|
## 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`.
|
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.
|
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.
|
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
|
## Project layout
|
||||||
|
|
||||||
Each of `Manuscript/`, `ResearchReport/`, and `Supplements/` is its own Quarto project with its own `_quarto.yml`, `index.qmd`, `data/`, and `figures/` folders.
|
Each of `Manuscript/`, `ResearchReport/`, and `Supplements/` is its own Quarto project with its own `_quarto.yml`, `index.qmd`, `data/`, and `figures/` folders.
|
||||||
|
|
||||||
```
|
```
|
||||||
ScientificManuscriptTemplate/
|
ScientificManuscriptTemplate/
|
||||||
├── Manuscript/ ← the paper itself
|
├── Manuscript/ ← the paper itself
|
||||||
├── ResearchReport/ ← longer-form report
|
├── ResearchReport/ ← longer-form report
|
||||||
├── Supplements/ ← supplementary materialss
|
├── Supplements/ ← supplementary materialss
|
||||||
├── resources/ ← shared across all three projects
|
├── resources/ ← shared across all three projects
|
||||||
│ ├── references.bib ← biblatex references
|
│ ├── references.bib ← biblatex references
|
||||||
│ ├── apa7.csl ← citation style, grab from https://www.zotero.org/styles/
|
│ ├── apa7.csl ← citation style, grab from https://www.zotero.org/styles/
|
||||||
│ ├── custom-reference-doc.docx ← docx template
|
│ ├── custom-reference-doc.docx ← docx template
|
||||||
│ └── author_profiles/
|
│ └── author_profiles/
|
||||||
│ ├── _quarto-default.yml ← real author/affiliation metadata
|
│ ├── _quarto-default.yml ← real author/affiliation metadata
|
||||||
│ └── _quarto-anonymized.yml ← anonymized-profile metadata
|
│ └── _quarto-anonymized.yml ← anonymized-profile metadata
|
||||||
├── Taskfile.yml ← run commands from here for the whole project
|
├── Taskfile.yml ← run commands from here for the whole project
|
||||||
└── finalized/ ← created by `task finalize`, date-stamped output
|
└── finalized/ ← created by `task finalize`, date-stamped output
|
||||||
```
|
```
|
||||||
|
|
||||||
## Writing content
|
## 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.
|
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.
|
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
|
## 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.
|
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
|
## 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.
|
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:
|
**Render one project**, from inside that project's folder:
|
||||||
|
|
||||||
```
|
```
|
||||||
cd Manuscript
|
cd Manuscript
|
||||||
task render # default profile, all formats
|
task render # default profile, all formats
|
||||||
task render:anonymized # anonymized profile, all formats
|
task render:anonymized # anonymized profile, all formats
|
||||||
task render:html # single format, default profile
|
task render:html # single format, default profile
|
||||||
task render:docx
|
task render:docx
|
||||||
task render:pdf
|
task render:pdf
|
||||||
task render:jats
|
task render:jats
|
||||||
```
|
```
|
||||||
|
|
||||||
**Or run any project's task from the repo root**, using its namespace:
|
**Or run any project's task from the repo root**, using its namespace:
|
||||||
|
|
||||||
```
|
```
|
||||||
task manuscript:render
|
task manuscript:render
|
||||||
task researchreport:render:anonymized
|
task researchreport:render:anonymized
|
||||||
task supplements:render:docx
|
task supplements:render:docx
|
||||||
```
|
```
|
||||||
|
|
||||||
**Render everything at once**, from the repo root:
|
**Render everything at once**, from the repo root:
|
||||||
|
|
||||||
```
|
```
|
||||||
task render:all # all three projects, default profile
|
task render:all # all three projects, default profile
|
||||||
task render:all:anonymized # all three projects, anonymized profile
|
task render:all:anonymized # all three projects, anonymized profile
|
||||||
```
|
```
|
||||||
|
|
||||||
## Packaging and finalizing
|
## Packaging and finalizing
|
||||||
|
|
||||||
```
|
```
|
||||||
task manuscript:package # zip Manuscript's default output
|
task manuscript:package # zip Manuscript's default output
|
||||||
task manuscript:package:data # zip Manuscript/data into data.zip
|
task manuscript:package:data # zip Manuscript/data into data.zip
|
||||||
task package:all # package every project, both profiles, plus data
|
task package:all # package every project, both profiles, plus data
|
||||||
task finalize # render everything, package everything,
|
task finalize # render everything, package everything,
|
||||||
# collect it all into finalized/<today's date>/
|
# 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.
|
`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
|
## Cleaning up
|
||||||
|
|
||||||
> [!WARNING]
|
> [!WARNING]
|
||||||
> Be careful using this: the command also cleans caches, meaning that all computations will have to be re-evaluated.
|
> 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 manuscript:clean # remove Manuscript's _output, .quarto, and stray cache folders
|
||||||
task clean:all # same, for all three projects
|
task clean:all # same, for all three projects
|
||||||
```
|
```
|
||||||
Reference in New Issue
Block a user