From bd337d3512ee2d215796565cc23edca64d3c17e2 Mon Sep 17 00:00:00 2001 From: Michael Beck Date: Fri, 19 Jun 2026 15:33:09 +0000 Subject: [PATCH] Update README.md --- README => README.md | 204 ++++++++++++++++++++++---------------------- 1 file changed, 102 insertions(+), 102 deletions(-) rename README => README.md (97%) diff --git a/README b/README.md similarity index 97% rename from README rename to README.md index cab6d23..f0c9576 100644 --- a/README +++ b/README.md @@ -1,103 +1,103 @@ -# 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// -``` - -`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 +# 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// +``` + +`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 ``` \ No newline at end of file