🛠️ VS Code Extension¶

Enhance VS Code for scientific writing with the official Rxiv-Maker extension. Get syntax highlighting, intelligent autocompletion, and integrated build commands for seamless manuscript development.

Overview¶

The Rxiv-Maker VS Code extension provides a comprehensive editing experience tailored specifically for scientific manuscript authoring. It bridges the gap between traditional text editing and specialized academic writing tools.

Key Features¶

• 🎨 Syntax Highlighting: Rich highlighting for enhanced Markdown, Python code blocks, and LaTeX injection
• 🔗 Citation Autocompletion: Intelligent suggestions from your BibTeX files
• 📍 Cross-Reference Management: Navigate and validate internal references
• ⚡ One-Click PDF Generation: Integrated build commands with progress tracking
• 🔍 Real-Time Validation: Feedback on syntax and references
• 📁 Project Templates: Templates for different manuscript types

Installation¶

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Rxiv-Maker"
4. Click Install

Features Walkthrough¶

1. Enhanced Syntax Highlighting¶

The extension provides rich syntax highlighting for Rxiv-Maker's enhanced Markdown:

Python Code Blocks:

{{py:exec
import pandas as pd           # Python syntax highlighting
df = pd.read_csv("data.csv")  # With intelligent colorization
result = df.mean()
}}

LaTeX Injection:

{{tex: $\langle\psi|\phi\rangle$}}   # Math mode detection
{{tex: \SI{273.15}{\kelvin}}}        # SI units highlighting

Cross-References:

See Figure @fig:results               # Reference highlighting
As shown in @eq:schrodinger          # Equation references

Citations:

Previous work [@smith2023; @doe2024]  # Citation highlighting

Syntax Highlighting in Action¶

Enhanced syntax highlighting demonstrates the extension's comprehensive support for scientific writing features including Python code blocks, mathematical notation, cross-references, citations, and LaTeX injection.

2. Citation Autocompletion¶

Intelligent citation suggestions from your BibTeX files:

Citation Autocompletion Demo [Demo GIF coming soon - showing intelligent citation suggestions from BibTeX files]

Features: - Auto-detection of .bib files in your project - Fuzzy search across author names, titles, and keywords - Preview tooltips showing full citation information - Multi-citation support with proper formatting

Setup: 1. Place your .bib files in your manuscript directory 2. The extension automatically detects and indexes them 3. Type [@ to trigger citation completion 4. Select from intelligent suggestions

3. Cross-Reference Management¶

Navigate and validate internal document references:

Features: - Go to definition for figures, tables, and equations - Find all references to see where items are cited - Broken reference detection with real-time warnings - Hover previews showing referenced content

Usage:

![My Analysis](FIGURES/plot.py)
{#fig:analysis}                    # Definition

See @fig:analysis for details.     # Reference (Ctrl+Click to navigate)

4. Integrated Build Commands¶

One-click PDF generation with progress tracking:

Command Palette (Ctrl+Shift+P / Cmd+Shift+P): - Rxiv: Generate PDF - Build your manuscript - Rxiv: Clean Output - Clean build artifacts - Rxiv: Validate Manuscript - Check for errors - Rxiv: Track Changes - Compare manuscript versions

Status Bar Integration: - Build progress indicator - Error/warning counts - Quick access to common commands

Build Integration Demo [Demo GIF coming soon - showing one-click PDF generation with progress tracking]

5. Project Templates¶

Templates for different manuscript types:

Available Templates: - arXiv Preprint - Standard preprint structure for physics/math/CS - bioRxiv Preprint - Life sciences preprint format - medRxiv Preprint - Medical sciences preprint format - Computational Preprint - Python-heavy analysis preprint

Usage: 1. Ctrl+Shift+P → Rxiv: Create New Manuscript 2. Select template type 3. Choose destination folder 4. Extension creates complete project structure

6. Real-Time Validation¶

Feedback on common issues:

Validation Features: - Syntax errors in Python code blocks - Missing figure files and broken paths - Invalid citations and missing BibTeX entries - Malformed cross-references - LaTeX syntax issues in injection blocks

Visual Indicators: - Red squiggles for errors - Yellow squiggles for warnings - Hover tooltips with detailed explanations - Problems panel integration

Configuration¶

Extension Settings¶

Access via File > Preferences > Settings and search for "Rxiv-Maker":

{
  "rxivMaker.buildCommand": "rxiv pdf",
  "rxivMaker.autoSave": true,
  "rxivMaker.validateOnType": true,
  "rxivMaker.bibFile": "references.bib",
  "rxivMaker.previewEnabled": true,
  "rxivMaker.pythonPath": "python3"
}

Key Settings:

Workspace Configuration¶

Create .vscode/settings.json in your manuscript directory:

{
  "rxivMaker.bibFile": "REFERENCES/main.bib",
  "rxivMaker.buildCommand": "rxiv pdf --engine local",
  "rxivMaker.validateOnType": false,
  "files.associations": {
    "*.md": "rxiv-markdown"
  }
}

Keybindings¶

Default keyboard shortcuts:

Custom Keybindings (keybindings.json):

[
  {
    "key": "ctrl+alt+p",
    "command": "rxivMaker.generatePDF",
    "when": "editorLangId == rxiv-markdown"
  },
  {
    "key": "ctrl+alt+c",
    "command": "rxivMaker.insertCitation",
    "when": "editorLangId == rxiv-markdown"
  }
]

Advanced Workflows¶

Multi-File Projects¶

For complex manuscripts with multiple files:

MANUSCRIPT/
├── 01_INTRODUCTION.md
├── 02_METHODS.md
├── 03_RESULTS.md
├── 04_DISCUSSION.md
├── REFERENCES/
│   ├── main.bib
│   └── supplementary.bib
└── .vscode/
    └── settings.json

Workspace settings:

{
  "rxivMaker.multiFile": true,
  "rxivMaker.mainFile": "01_INTRODUCTION.md",
  "rxivMaker.bibFiles": [
    "REFERENCES/main.bib",
    "REFERENCES/supplementary.bib"
  ]
}

Collaborative Writing¶

For team projects with version control:

Recommended Setup: 1. Shared settings: Commit .vscode/settings.json 2. Consistent paths: Use relative paths for all resources 3. Git integration: Extension works seamlessly with Git 4. Branch awareness: Different settings per branch if needed

Python Environment Integration¶

Configure Python interpreter for code validation:

{
  "rxivMaker.pythonPath": "/path/to/your/python",
  "rxivMaker.pythonEnv": ".venv",
  "rxivMaker.validatePython": true
}

The extension will: - Use specified Python for syntax checking - Validate imports against available packages - Show intelligent suggestions for scientific libraries

Snippets and Shortcuts¶

Built-in Snippets¶

Type snippet prefix and press Tab:

Custom Snippets¶

Add to markdown.json snippets file:

{
  "Statistical Analysis": {
    "prefix": "stats",
    "body": [
      "{{py:exec",
      "from scipy import stats",
      "import numpy as np",
      "",
      "# Statistical analysis",
      "$1",
      "}}",
      "",
      "The analysis shows $2 (p = {{py:get $3}})."
    ],
    "description": "Statistical analysis template"
  }
}

Troubleshooting¶

Common Issues¶

Extension not detecting BibTeX files:

{
  "rxivMaker.bibSearchPaths": [
    ".",
    "REFERENCES",
    "../shared-bibliography"
  ]
}

Build command not working: 1. Verify rxiv is in PATH 2. Check terminal integration: Terminal > Select Default Profile 3. Use absolute path: "buildCommand": "/usr/local/bin/rxiv pdf"

Syntax highlighting not working: 1. Ensure file association: "files.associations": {"*.md": "rxiv-markdown"} 2. Reload window: Developer: Reload Window 3. Check extension is enabled and active

Python validation errors:

{
  "rxivMaker.pythonPath": "python3",
  "rxivMaker.pythonEnv": ".venv",
  "rxivMaker.additionalPaths": ["src/py"]
}

Debug Mode¶

Enable detailed logging:

{
  "rxivMaker.logLevel": "debug",
  "rxivMaker.showLogs": true
}

Access logs via View > Output > Rxiv-Maker.

Tips and Best Practices¶

1. Organize Your Workspace¶

MANUSCRIPT/
├── .vscode/
│   ├── settings.json      # Project-specific settings
│   └── launch.json        # Debug configurations
├── FIGURES/
├── REFERENCES/
└── src/py/               # Python modules

2. Use Workspace Settings¶

Commit .vscode/settings.json for team consistency:

{
  "rxivMaker.buildCommand": "rxiv pdf --engine local",
  "rxivMaker.bibFile": "REFERENCES/main.bib",
  "editor.wordWrap": "on",
  "editor.rulers": [80],
  "files.trimTrailingWhitespace": true
}

3. Leverage Git Integration¶

• Branch-specific settings: Different configs per feature branch
• Ignored files: Add .vscode/launch.json to .gitignore for personal debugging
• Shared snippets: Commit useful snippets for team use

4. Optimize for Performance¶

For large projects:

{
  "rxivMaker.validateOnType": false,
  "rxivMaker.indexingDelay": 1000,
  "rxivMaker.maxFileSize": "1MB"
}

Integration with Other Extensions¶

Recommended Extensions¶

Writing and Editing: - Spell Right: Spell checking for academic writing - Better Comments: Enhanced comment highlighting - Markdown All in One: Additional Markdown features

Python Development: - Python: Official Python extension for code validation - Pylance: Advanced Python language support

Git and Collaboration: - GitLens: Enhanced Git capabilities - Live Share: Real-time collaborative editing

Extension Compatibility¶

The Rxiv-Maker extension works well with:

• Markdown extensions: Enhances rather than replaces
• Python extensions: Provides additional Python-specific features
• Git extensions: Full version control integration
• Theme extensions: Inherits your preferred color scheme

Updates and Releases¶

Auto-Updates¶

The extension updates automatically via VS Code's extension manager. Check for updates:

1. Extensions view
2. Search for "Rxiv-Maker"
3. Click Update if available

Release Notes¶

Major releases include:

• New language features: Support for latest Rxiv-Maker syntax
• Enhanced validation: Better error detection and suggestions
• Performance improvements: Faster indexing and completion
• Bug fixes: Resolved issues and stability improvements

Preview Features¶

Enable experimental features:

{
  "rxivMaker.previewFeatures": true,
  "rxivMaker.beta": true
}

Summary¶

The VS Code extension transforms your editing experience with:

1. Professional syntax highlighting for all Rxiv-Maker features
2. Intelligent autocompletion for citations and references
3. Integrated build system with one-click PDF generation
4. Real-time validation and error detection
5. Project templates for quick manuscript setup

Perfect for researchers who want a powerful, integrated development environment for scientific writing.

Get Started: 1. Install the extension 2. Open your manuscript project 3. Configure workspace settings 4. Start writing with enhanced productivity

Next Steps: - Python Execution → for dynamic content - LaTeX Injection → for advanced typesetting - Examples → for real-world workflows