From 4a943b674794c757c19ac519d3975ecd791dc138 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 24 Aug 2026 21:17:55 +0000 Subject: [PATCH 1/3] Split the Overleaf guide into Dropbox and Git paths Call out the hook difference up front: Dropbox needs only pdflatex, while Git needs pdflatex plus pull and push (or a Git hook). Co-authored-by: ss.shankar505 --- docs/feature-catalog.json | 2 +- docs/guides/overleaf.mdx | 71 +++++++++++++++++++++++----- scripts/generate-feature-catalog.mjs | 2 +- 3 files changed, 62 insertions(+), 13 deletions(-) diff --git a/docs/feature-catalog.json b/docs/feature-catalog.json index c0d8f05..9930b3c 100644 --- a/docs/feature-catalog.json +++ b/docs/feature-catalog.json @@ -815,7 +815,7 @@ { "id": "guides-overleaf-01", "area": "Automation", - "feature": "Edit, build, preview, and sync an Overleaf project", + "feature": "Edit, build, preview, and sync an Overleaf project with Dropbox or Git", "targetPage": "guides/overleaf" }, { diff --git a/docs/guides/overleaf.mdx b/docs/guides/overleaf.mdx index 289b306..2eaa1e3 100644 --- a/docs/guides/overleaf.mdx +++ b/docs/guides/overleaf.mdx @@ -2,11 +2,40 @@ title: "Edit an Overleaf project" --- -Use this workflow when an Overleaf project is available through Git. You can edit the local files in DocWriter and use Git to move accepted changes between the local repository and Overleaf. +You can edit an Overleaf project in DocWriter in two ways. The local writing steps are the same. The methods differ in how files travel between your machine and Overleaf, and in which hooks you add. -## Get the project +| Method | How files move | Hooks you add | +| --- | --- | --- | +| [Dropbox sync](#get-the-project-with-dropbox) | Dropbox copies saved files both ways | `pdflatex` only | +| [Git](#get-the-project-with-git) | You pull and push a Git repository | `pdflatex` and Git | -Clone the project so DocWriter and your TeX tools can work with local files. Connect the Overleaf project to GitHub, or copy its Git URL from the Overleaf project menu. Then run: +Choose one method for the project. Do not enable Dropbox and Git on the same Overleaf project. + + + + Open the Dropbox folder for the project. Add only the `pdflatex` hook. Dropbox sends accepted files back to Overleaf. + + + Clone the Overleaf or GitHub repository. Add the `pdflatex` hook and Git. You push accepted files back yourself, or with a Git hook. + + + +## Get the project with Dropbox + +Use Dropbox when Overleaf already copies the project into a local folder. Link Dropbox in Overleaf **Account Settings**, then confirm the project folder exists under `Dropbox/Apps/Overleaf`. Open that project folder, not the parent `Overleaf` folder. + +```sh +cd ~/Dropbox/Apps/Overleaf/my-paper +ls +``` + +You should see the TeX source. Overleaf premium Dropbox sync is required. See [Overleaf's Dropbox documentation](https://docs.overleaf.com/integrations-and-add-ons/dropbox) if the folder is missing. + +Continue with [Open the project](#open-the-project). After you accept an edit, [Dropbox sends the change back](#send-the-change-back-with-dropbox). You do not add a Git hook. + +## Get the project with Git + +Use Git when you clone the project and move accepted files with pull and push. Connect the Overleaf project to GitHub, or copy its Git URL from the Overleaf project menu. Then run: ```sh git clone ~/writing/my-paper @@ -15,15 +44,19 @@ cd ~/writing/my-paper Confirm that `~/writing/my-paper` contains the TeX source and that `git status` runs there without an error. Pull before each writing session so the local files include changes made in Overleaf. +Continue with [Open the project](#open-the-project). After you accept an edit, [send the change back with Git](#send-the-change-back-with-git). You need both the `pdflatex` hook and Git. + ## Open the project -Start DocWriter in watch mode so it opens this project and watches its files for outside changes: +Start DocWriter in watch mode so it opens this project and watches its files for outside changes. Use the Dropbox folder or the Git clone you just confirmed: ```sh docwriter --watch ~/writing/my-paper ``` -Open the main TeX file. You should see the TeX source and the project files in the file tree. The files remain normal workspace files, so Git and Overleaf can still track them. +For Dropbox, pass the project folder under `Dropbox/Apps/Overleaf`. Watch mode matters for both methods: Dropbox writes Overleaf changes onto disk, and a Git pull does the same. + +Open the main TeX file. You should see the TeX source and the project files in the file tree. The files remain normal workspace files, so Dropbox or Git can still track them. ![A TeX project open in the source editor](/images/overleaf-tex-open.png) @@ -31,7 +64,9 @@ Open the main TeX file. You should see the TeX source and the project files in t ## Build the PDF -Build the PDF so you can catch TeX errors and review the formatted paper after each accepted edit. Install a TeX distribution that provides `pdflatex`, `bibtex`, and `synctex`. +Both methods need the `pdflatex` hook so you can catch TeX errors and review the formatted paper after each accepted edit. The Git method adds a second hook later. Do not add a Git hook for Dropbox. + +Install a TeX distribution that provides `pdflatex`, `bibtex`, and `synctex`. Confirm that each command is available on `PATH`: @@ -81,18 +116,32 @@ The `%` starts a TeX comment, so LaTeX ignores the request while it waits. Revie Run the build again after accepting the change. Confirm that the request is gone, the accepted source is present, the hook finishes successfully, and the PDF shows the intended revision. -## Send the change back +Then send the accepted files back with the method you chose: [Dropbox](#send-the-change-back-with-dropbox) or [Git](#send-the-change-back-with-git). + +## Send the change back with Dropbox + +Dropbox copies the saved source files to Overleaf. You do not add a Git hook. Keep only the `pdflatex` hook. -Use Git to send the accepted local files back to the remote repository connected to Overleaf. Review the Git diff, then commit and push: +Accepting an edit writes the workspace file. Wait for Dropbox to finish syncing, then open the Overleaf project and confirm the accepted source is there. If Overleaf still shows the old text, use **Sync this project now** in the project's Dropbox integration. + +Do not upload the locally compiled PDF into the Overleaf project. Overleaf builds its own PDF from the source. If Dropbox creates conflict copies of `.pdf`, `.aux`, or `.log` files, add [Dropbox ignore rules](https://docs.overleaf.com/integrations-and-add-ons/dropbox#avoiding-conflicts-on-pdf-and-compiled-output-files) for those build outputs. + +Read [Hooks](/customize/hooks) if you need to change the `pdflatex` command or output path. + +## Send the change back with Git + +Git needs a second step after the `pdflatex` hook. Review the Git diff, then commit and push: ```sh git status git diff -git add . +git add -A -- ':(exclude).docwriter' ':(exclude).claude' ':(exclude)CLAUDE.md' git commit -m "Revise manuscript" git push ``` -Confirm that `git status` is clean and that the remote repository contains the new commit. You pull and push changes yourself by default. You can add a Git hook later, but first confirm that manual pull and push work without a credential prompt. +The `:(exclude)` paths keep local agent files out of the Overleaf or GitHub remote. Confirm that `git status` is clean except for those excluded files, and that the remote repository contains the new commit. + +You pull and push changes yourself by default. Add a Git hook only after a manual pull and push work without a credential prompt. Open **Settings**, then **Hooks**, and choose a Git template. The private template skips `.docwriter/`, `.claude/`, and `CLAUDE.md`. -Read [Hooks](/customize/hooks) before automating the build or Git commands. +Read [Hooks](/customize/hooks) before you automate the build or Git commands. Read [Pandoc, Mermaid, and Git](/automation/example-projects#git) for the Git templates. diff --git a/scripts/generate-feature-catalog.mjs b/scripts/generate-feature-catalog.mjs index ff43151..3fa9073 100644 --- a/scripts/generate-feature-catalog.mjs +++ b/scripts/generate-feature-catalog.mjs @@ -194,7 +194,7 @@ const pageFeatures = { ['Agent', 'Write a blog post and add a supported citation', C, 'Blog writing example'] ], 'guides/overleaf': [ - ['Automation', 'Edit, build, preview, and sync an Overleaf project', C, 'Overleaf guide'], + ['Automation', 'Edit, build, preview, and sync an Overleaf project with Dropbox or Git', C, 'Overleaf guide'], ['Workspace', 'Use forward and reverse SyncTeX between source and PDF', T, 'Preview covers part of the flow'], ['Automation', 'Find a same name PDF automatically for a TeX file', M, 'No page'] ], From 8d9f65b3d23e99e82dfe9f3a4bcc4964a210e412 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 24 Aug 2026 21:29:53 +0000 Subject: [PATCH 2/3] Show Overleaf hook choices as wrapping text Replace the comparison table so narrow viewports still show that Dropbox needs only pdflatex and Git needs both hooks. Co-authored-by: ss.shankar505 --- docs/guides/overleaf.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/guides/overleaf.mdx b/docs/guides/overleaf.mdx index 2eaa1e3..c491a95 100644 --- a/docs/guides/overleaf.mdx +++ b/docs/guides/overleaf.mdx @@ -4,10 +4,8 @@ title: "Edit an Overleaf project" You can edit an Overleaf project in DocWriter in two ways. The local writing steps are the same. The methods differ in how files travel between your machine and Overleaf, and in which hooks you add. -| Method | How files move | Hooks you add | -| --- | --- | --- | -| [Dropbox sync](#get-the-project-with-dropbox) | Dropbox copies saved files both ways | `pdflatex` only | -| [Git](#get-the-project-with-git) | You pull and push a Git repository | `pdflatex` and Git | +- **[Dropbox sync](#get-the-project-with-dropbox):** Dropbox copies saved files both ways. Add the `pdflatex` hook only. +- **[Git](#get-the-project-with-git):** You pull and push a Git repository. Add the `pdflatex` hook and Git. Choose one method for the project. Do not enable Dropbox and Git on the same Overleaf project. @@ -31,7 +29,7 @@ ls You should see the TeX source. Overleaf premium Dropbox sync is required. See [Overleaf's Dropbox documentation](https://docs.overleaf.com/integrations-and-add-ons/dropbox) if the folder is missing. -Continue with [Open the project](#open-the-project). After you accept an edit, [Dropbox sends the change back](#send-the-change-back-with-dropbox). You do not add a Git hook. +Continue with [Open the project](#open-the-project). After you accept an edit, [Dropbox sends the change back](#send-the-change-back-with-dropbox). Add only the `pdflatex` hook. Do not add a Git hook. ## Get the project with Git From f045296c6f033501798d5e9c57126d73256e06c8 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 24 Aug 2026 21:49:19 +0000 Subject: [PATCH 3/3] Nest Dropbox and Git under the shared Overleaf steps Treat Dropbox and Git as two ways to get and return files, not as top-level sections beside open, build, preview, and edit. Co-authored-by: ss.shankar505 --- docs/guides/overleaf.mdx | 37 ++++++++++++++++--------------------- 1 file changed, 16 insertions(+), 21 deletions(-) diff --git a/docs/guides/overleaf.mdx b/docs/guides/overleaf.mdx index c491a95..9db72fb 100644 --- a/docs/guides/overleaf.mdx +++ b/docs/guides/overleaf.mdx @@ -2,23 +2,18 @@ title: "Edit an Overleaf project" --- -You can edit an Overleaf project in DocWriter in two ways. The local writing steps are the same. The methods differ in how files travel between your machine and Overleaf, and in which hooks you add. +You can keep an Overleaf project in a local folder with Dropbox or with Git. The rest of this guide is the same after that: open the folder, build a PDF, preview it, and ask for an edit. The methods differ only in how you get the files and how accepted files return to Overleaf. -- **[Dropbox sync](#get-the-project-with-dropbox):** Dropbox copies saved files both ways. Add the `pdflatex` hook only. -- **[Git](#get-the-project-with-git):** You pull and push a Git repository. Add the `pdflatex` hook and Git. +- **Dropbox:** Dropbox copies saved files both ways. Add the `pdflatex` hook only. +- **Git:** You pull and push a Git repository. Add the `pdflatex` hook and Git. Choose one method for the project. Do not enable Dropbox and Git on the same Overleaf project. - - - Open the Dropbox folder for the project. Add only the `pdflatex` hook. Dropbox sends accepted files back to Overleaf. - - - Clone the Overleaf or GitHub repository. Add the `pdflatex` hook and Git. You push accepted files back yourself, or with a Git hook. - - +## Get the project -## Get the project with Dropbox +Use one of these two ways to get a local folder, then continue with [Open the project](#open-the-project). + +### Dropbox Use Dropbox when Overleaf already copies the project into a local folder. Link Dropbox in Overleaf **Account Settings**, then confirm the project folder exists under `Dropbox/Apps/Overleaf`. Open that project folder, not the parent `Overleaf` folder. @@ -29,9 +24,7 @@ ls You should see the TeX source. Overleaf premium Dropbox sync is required. See [Overleaf's Dropbox documentation](https://docs.overleaf.com/integrations-and-add-ons/dropbox) if the folder is missing. -Continue with [Open the project](#open-the-project). After you accept an edit, [Dropbox sends the change back](#send-the-change-back-with-dropbox). Add only the `pdflatex` hook. Do not add a Git hook. - -## Get the project with Git +### Git Use Git when you clone the project and move accepted files with pull and push. Connect the Overleaf project to GitHub, or copy its Git URL from the Overleaf project menu. Then run: @@ -42,8 +35,6 @@ cd ~/writing/my-paper Confirm that `~/writing/my-paper` contains the TeX source and that `git status` runs there without an error. Pull before each writing session so the local files include changes made in Overleaf. -Continue with [Open the project](#open-the-project). After you accept an edit, [send the change back with Git](#send-the-change-back-with-git). You need both the `pdflatex` hook and Git. - ## Open the project Start DocWriter in watch mode so it opens this project and watches its files for outside changes. Use the Dropbox folder or the Git clone you just confirmed: @@ -62,7 +53,7 @@ Open the main TeX file. You should see the TeX source and the project files in t ## Build the PDF -Both methods need the `pdflatex` hook so you can catch TeX errors and review the formatted paper after each accepted edit. The Git method adds a second hook later. Do not add a Git hook for Dropbox. +Both methods need the `pdflatex` hook so you can catch TeX errors and review the formatted paper after each accepted edit. Git adds a second hook later, when you [send the change back](#send-the-change-back). Do not add a Git hook for Dropbox. Install a TeX distribution that provides `pdflatex`, `bibtex`, and `synctex`. @@ -114,9 +105,13 @@ The `%` starts a TeX comment, so LaTeX ignores the request while it waits. Revie Run the build again after accepting the change. Confirm that the request is gone, the accepted source is present, the hook finishes successfully, and the PDF shows the intended revision. -Then send the accepted files back with the method you chose: [Dropbox](#send-the-change-back-with-dropbox) or [Git](#send-the-change-back-with-git). +Then [send the change back](#send-the-change-back) with the same method you used to get the project. + +## Send the change back + +Use the same Dropbox or Git method you chose above. -## Send the change back with Dropbox +### Dropbox Dropbox copies the saved source files to Overleaf. You do not add a Git hook. Keep only the `pdflatex` hook. @@ -126,7 +121,7 @@ Do not upload the locally compiled PDF into the Overleaf project. Overleaf build Read [Hooks](/customize/hooks) if you need to change the `pdflatex` command or output path. -## Send the change back with Git +### Git Git needs a second step after the `pdflatex` hook. Review the Git diff, then commit and push: