cursor-viewer Usage
English | 简体中文 | 繁體中文
cursor-viewer is an enhanced Cursor / VS Code file preview and processing extension, specifically optimized for Cursor Chat's @ references.
This project is based on the open-source vscode-office (also commonly referred to as office-viewer) after modification: the core file preview capability comes from the open-source project; adding the @ reference workflow improves interaction with cursor chat; and it adds the feature that the browsing interface background changes according to the system theme.
Reference repository: cweijan/vscode-office.
Cursor Chat Interaction
Practical workflow in Cursor
- After you install and enable this extension in Cursor, you can turn the following files into formats that Cursor can easily understand.
- Word documents：
.doc、.docx、.dotx
- Excel spreadsheets：
.xlsx、.xls
Benefit of this approach: Cursor is more friendly to text-based formats like PDF / CSV that are “well-structured”, compared with directly uploading the original Office files; it is more stable and controllable.
Select a supported file in the file tree sidebar, right-click it, and run one of the following commands.
Add to Cursor Chat (as PDF)：suitable for Word and other document-type files.Add to Cursor Chat (as CSV)：suitable for Excel table files.
The extension will:
- generate a temporary PDF / CSV file in the background;
- automatically open it in a new tab for preview;
- copy the relative path of the temporary file to your clipboard.
Back in Cursor Chat, after typing @:
- directly paste the path you just copied, or
- choose that path from the popped-up file candidates.
At this point, Cursor can read the content of this temporary PDF / CSV. You can ask it to summarize, compare, or write scripts to process data, etc.
Notes on .doc Conversion
.doc (older Word format) usually relies on an external conversion engine (such as LibreOffice or local Office) to convert it to PDF.- If your system does not have those tools installed or is not configured correctly, the extension will prompt a warning/error when attempting to convert
.doc.
- If you run into this, suggestions are:
- try to first manually save
.doc as .docx locally, then use the extension; or
- check whether your system has command-line conversion support for Office/LibreOffice installed, and configure it according to the extension documentation.
File browsing and preview capabilities
Besides preparing “readable versions” of documents for Cursor, cursor-viewer itself is also a fully-featured file previewer, which can greatly reduce the cost of switching back and forth between different applications.
Theme auto-adaptation: the preview background follows Cursor system colors
When you switch between dark/light (or change the color theme) in Cursor/VS Code, the preview webview background will update synchronously; that is, the background color you see while browsing files changes with your Cursor system theme.
Office and common documents
- Excel：
.xls、.xlsx、.xlsm、.csv、.ods
- supports directly previewing tables in the editor;
- can be saved (note: saving
.xlsx again may lose some formatting; .csv does not support GBK Chinese encoding).
- Word：
.docx、.dotx
- supports directly reading in the editor;
- PDF：
.pdf
- has built-in rendering capabilities, so you can preview without extra tools.
- Fonts：
.ttf、.otf、.woff、.woff2
- previews font styles, suitable for front-end/design related work.
- Images：common image formats (such as
.png/.jpg/.gif/.webp/...)
- previews directly in the panel without leaving the editor.
- Markdown：
.md/.markdown (WYSIWYG editing based on Vditor)
- SVG：
.svg
- HTML：when editing HTML, you can open the real-time preview panel via
Ctrl + Shift + V, making it convenient to debug static pages.
- HTTP request files：
.http
- write requests directly in the editor, and send with
Ctrl + Enter / Cmd + Enter.
- you can save or copy the responses; suitable for API debugging and interface documentation/automation scripts together with Cursor.
- Windows Registry files：
.reg
- provides
REG: Jump to registry key and other functions, convenient for quickly browsing and jumping.
- Compressed/Archive files：
.zip、.jar、.vsix、.rar、.apk
- supports browsing the compressed directory tree;
- you can directly open and preview a single file inside; if needed, you can extract the whole archive.
When working in Cursor, these previewers let you view any related files “in place”; then organize the key content into documents as needed, and further process them through Cursor.
Recommended workflow in the project
By combining cursor-viewer and Cursor, you can build an efficient “materials → AI assistant” workflow:
- Organize materials：put Word/Excel/PDF/Markdown/HTTP and other files into the current workspace uniformly.
- Preview in place：open directly in the file tree on the left side of Cursor, and use the extension's previewers to quickly browse content.
- Convert and reference：
- for complex Word/Excel, use
Add to Cursor Chat (as PDF/CSV) to generate temporary files;
- use
@ to reference these files, so Cursor fully understands the original content.
- Iterate：based on Cursor's output, go back to the original files to make modifications or supplements, and then export/reference again.
