Skip to content
Ahmad Ammar

7. How to edit our documents

7.1 From a published page

Turn on the Admin bar once in a browser by adding ?admin=on to any page address (?admin=off hides it). At the bottom of every page of a guide it then offers:

  • All chapters in Studio: the whole document in the local editor (below), opened at the chapter you were reading. Studio must be running.

  • Edit … in VS Code: that chapter’s .tex file on this computer.

  • Edit in browser: the same file in GitHub’s web editor. The change is committed to the repository, but the page changes only after a rebuild.

7.2 Studio

Start it with

python -m research_helpers.stack studio

and open http://127.0.0.1:8770/. It lists every document with a document.toml. A document opens as one long page: each chapter’s LaTeX on the left, its rendering on the right.

  • Type in the LaTeX, and the rendering follows after a pause.

  • Click a plain paragraph or heading in the rendering and type there. When you leave it, that paragraph alone is written back into the LaTeX. Mathematics, citations and references show as grey chips that are carried over unchanged. Paragraphs with environments or equations are edited in the LaTeX: double-click them to jump there.

  • Click a figure to replace its image or edit its caption. Add figure, or dropping an image on the LaTeX, saves the image beside the others (never over one) and inserts a figure at the cursor.

  • Ctrl+S saves the changed chapters. It refuses if a file was changed elsewhere in the meantime.

  • Save and publish rebuilds the document, commits what the rebuild changed, and pushes. Documents listed in .stack-hold are never published.

The rendering is a quick approximation. For the exact PDF, use the VS Code task below.

7.3 VS Code

Run once per repository:

python -m research_helpers.stack editor .

Then, in any chapter, Ctrl+Shift+B builds the document’s PDF into build/preview/, and the task Rebuild this document’s web pages rebuilds the site’s pages for it. LaTeX lines wrap in the editor.

7.4 From the command line

python -m research_helpers.stack preview path/to/chapter.tex       # PDF
python -m research_helpers.stack preview path/to/chapter.tex web   # web pages
python build_guides.py <guide>                                     # the site's own build