Prodockit Authoring Assistant

A VS Code extension for prodockit-template coursework reports — turns the template's custom Markdown macros (\ref{}, \cite{}, \gls{}, figure/table captions, nav registration) into GUI pickers, live diagnostics, and hover previews instead of syntax you have to memorize.

Install from the VS Code Marketplace (search "Prodockit Authoring Assistant"), or build/sideload it from source below.

Requires a prodockit-template workspace. This extension is built around that template's specific conventions (docs/ layout, zensical.toml's nav, .bib files, attr_list-based glossary/acronym entries) — it activates on any Markdown file or a workspace containing zensical.toml, but most commands only do anything useful inside an actual prodockit-template project.

Sidebar

Click the Prodockit icon in the Activity Bar (left-hand icon strip) to open the Authoring Assistant view — a tree with four sections:

• Actions — Insert Image, Insert Table, Insert New Page, Start/Stop Preview (toggles based on whether it's running), Rebuild Index.
• Cross-References (\ref) — every heading found under docs/. Click one to insert \ref{id} at your cursor.
• Citations (\cite) — every entry in references.bib/bibliography.bib, marked "(unused)" if it's never actually \cite{}-d anywhere in docs/*.md - a cleanup signal before submission. Click one to insert \cite{key}.
• Glossary & Acronyms (\gls) — every entry in docs/acronyms.md/docs/glossary.md, same "(unused)" marking. Click one to insert \gls{id}.

No QuickPick popup, no remembering ids or keybindings — open the sidebar, click what you want to insert, and it lands wherever your cursor last was in a Markdown file (the sidebar has its own focus, so it remembers the last Markdown editor you were actually typing in rather than requiring it to still be focused). The tree refreshes automatically whenever the underlying index rebuilds (i.e. on every save of a .md/.bib/zensical.toml file).

The right-click/Command-Palette/keybinding versions below still work exactly the same — the sidebar is just a second way to reach the same data.

What it does

• Prodockit: Insert Cross-Reference... (Ctrl/Cmd+Alt+R) — search headings across docs/ and insert \ref{id} or \autoref{id} (toggle with the button in the picker's title bar).
• Prodockit: Insert Citation... (Ctrl/Cmd+Alt+C) — search entries in references.bib/bibliography.bib by author/title and insert \cite{key}.
• Prodockit: Insert Glossary/Acronym Term... (Ctrl/Cmd+Alt+G) — search docs/acronyms.md/docs/glossary.md and insert \gls{id}.
• Prodockit: Insert Image... (Ctrl/Cmd+Alt+I) — browse for an image, it's copied into docs/assets/ (renamed to avoid collisions), and a figure-caption block is inserted with a path relative to the current file.
• Paste an image directly into a Markdown file — same as "Insert Image...", triggered automatically as the preferred paste option (VS Code's own "insert as plain link" option is still available underneath it in the paste-control widget if you want that instead).
• Prodockit: Start Preview (parsed output) / Prodockit: Stop Preview — runs zensical serve, showing a status bar item ($(sync~spin) building / $(check) running, click to open the browser) instead of a raw terminal, with full output still available in the "Prodockit: Preview" Output Channel. If the project's own .vscode/tasks.json has a "Zensical: Serve (live preview)" task already running, this points you at that instead of starting a second server on the same port.
• Prodockit: Rebuild Reference Index — manually re-scans docs/*.md, *.bib, and zensical.toml (normally happens automatically on save).
• Prodockit: Insert Table... (Ctrl/Cmd+Alt+T) — prompts for column/row counts and a caption, inserts a Markdown table with the required table-caption | < block already wired up (omitting | < silently moves the caption below the table instead of above).
• Prodockit: Insert New Page... — creates a new docs/*.md page and adds it to zensical.toml's nav in one step, asking which section to file it under. Fixes the easy-to-forget step where a page exists on disk but never shows up in the build because nobody added it to nav. Opens zensical.toml afterward with the new line selected so you can confirm it landed in the right place before trusting it.
• Diagnostics — a broken/unresolved \ref{}, \autoref{}, \cite{}, or \gls{} id gets a warning squiggle as you type, before you ever run a build. Typing \citeref{} (inactive in this repo) is flagged too, pointing you at \cite{} instead.
• Hover — hover any \ref{}/\autoref{}/\cite{}/\gls{} call to see what it resolves to (the heading text, the formatted citation, or the glossary definition) without jumping to the source page.
• Word count — a status bar item shows the current page's rough word count (same algorithm the build's own word count uses) whenever you're editing a docs/*.md page that isn't marked exclude_from_word_count: true.

All insert commands are also in the editor's right-click menu and the Command Palette when a Markdown file is focused.

Why \cite{} and not \citeref{}

This repo's zensical.toml registers prodockit.bibliography (the .bib-file-based \cite{key} system) but not prodockit.citations (the older \citeref{id} attr_list system) — so the citation picker only ever inserts \cite{}. If a workspace's zensical.toml is edited to register prodockit.citations instead, Prodockit: Insert Citation... will warn rather than silently inserting syntax that won't resolve.

Installing

From the Marketplace (once published): Extensions view → search "Prodockit Authoring Assistant" → Install. Or via the command line: code --install-extension ZainAbdn.prodockit-authoring-assistant.

From a .vsix build (a release, or one you built yourself - see below):

code --install-extension prodockit-authoring-assistant-1.0.0.vsix

Or from the UI: Extensions view → ... menu (top right) → "Install from VSIX..." → pick the file.

Reload the window afterwards if VS Code doesn't prompt you to.

Building from source

Requires Node 22:

git clone https://github.com/ZainAbdn/prodockit-authoring-assistant.git
cd prodockit-authoring-assistant
npm install
npm run compile   # type-check + esbuild bundle to dist/
npm test          # runs the pure-logic unit tests (parsers, configReader, figureBlock, tableBlock, wordCount, navEditor)
npm run package   # produces prodockit-authoring-assistant-<version>.vsix

To develop/debug it: open this repo in VS Code and press F5 — this launches an Extension Development Host (npm run watch keeps dist/ rebuilt as you edit) pointed at a sibling prodockit-template checkout, so commands run against real content rather than an empty folder. .vscode/launch.json's args array has that path - edit it if your own template clone lives somewhere else.

Known limitations

• The picker for cross-references falls back to a best-effort slugified id (labeled "auto id, unverified") for headings without an explicit {: #id } — this approximates, but doesn't guarantee, the id prodockit.headings actually assigns at build time. If a \ref{}/\autoref{} you inserted renders as ??, add an explicit {: #id } to the target heading and re-pick.
• The .bib file reader extracts just enough (author/title/year) for a picker label — it isn't a full BibTeX parser and won't handle every valid .bib file shape (e.g. @string macros, cross-referenced entries).
• Image paste requires a VS Code build with DocumentPasteEditProvider support (bundled since a fairly recent VS Code release - see engines.vscode in package.json for the floor this extension declares).
• Prodockit: Insert New Page... edits zensical.toml's nav array with a text-based, "just enough" transform (not a full TOML writer) - it always opens the file with the new line selected afterward so you can verify placement before trusting it. Undo (Cmd/Ctrl+Z) if it's not where you expected.
• Diagnostics/hover resolve against the last-saved index, not unsaved edits to a different open file - e.g. adding a heading id in one tab won't clear a "no heading found" warning in another tab until you save the first one.