Scimax VS Code

✅ Overview

Scimax VS Code provides comprehensive bibliography and citation management inspired by Emacs org-ref. This system allows you to:

  • Manage BibTeX bibliography files

  • Insert and format citations in multiple styles

  • Follow citation links to PDFs, URLs, and notes

  • Search and browse your reference library

  • Export citations to various formats

  • Integrate with CrossRef and OpenAlex for metadata

The reference system seamlessly integrates with org-mode documents while also supporting Markdown and LaTeX formats.

✅ Setting Up Bibliography Files

Configuration

Configure your default bibliography files in VS Code settings (Preferences: Open Settings (UI) → search for "scimax ref"):

SettingDescription
scimax.ref.bibliographyFilesArray of .bib file paths (global)
scimax.ref.pdfDirectoryDirectory containing PDF files
scimax.ref.notesDirectoryDirectory for reference notes (.org files)
scimax.ref.defaultCiteStyleDefault citation style (cite, citet, citep)
scimax.ref.autoDownloadPdfAuto-download PDFs from DOI (experimental)

These files are used when you do not specify document-local bibliography files.

✅ Example Configuration

{
  "scimax.ref.bibliographyFiles": [
    "~/Documents/references.bib",
    "~/research/bibliography.bib"
  ],
  "scimax.ref.pdfDirectory": "~/Documents/papers/",
  "scimax.ref.notesDirectory": "~/Documents/notes/",
  "scimax.ref.defaultCiteStyle": "cite"
}

✅ Document-Local Bibliography Files

You can specify bibliography files per document using:

✅ Bibliography Keywords

Alternative org-mode syntax:

#+BIBLIOGRAPHY: ~/Documents/references.bib

✅ Workspace Bibliography Files

The extension automatically discovers all .bib files in your workspace and makes them available for citation completion.

✅ Creating a Bibliography File

Create a new .bib file manually or use the command:

Basic BibTeX entry structure:

@article{smith2024machine,
  author = {Smith, John and Doe, Jane},
  title = {Machine Learning for Scientific Computing},
  journal = {Journal of Computational Science},
  year = {2024},
  volume = {15},
  number = {3},
  pages = {123--145},
  doi = {10.1000/jcs.2024.0001}
}

✅ Inserting Citations

✅ Insert Citation Command

KeyCommand
C-c ]Insert citation (scimax.ref.insertCitation)

✅ Interactive Citation Insertion

  1. Press C-c ] or run command [[cmd:scimax.ref.insertCitation]]

  2. Search and select a reference (searches key, author, title, year)

  3. Choose citation style (cite, citet, citep, citeauthor, citeyear)

  4. Citation is inserted at cursor

✅ Appending to Existing Citations

When cursor is on an existing citation:

  1. Press C-c ]

  2. Select additional reference

  3. Key is automatically appended: (key1, key2)

The command detects when you're on a citation and adds the new key to the list.

✅ Citation Completion

Auto-completion triggers after typing:

  • cite: (org-mode)

  • @ (Markdown/Pandoc)

  • \cite{ (LaTeX)

Completion shows:

  • Citation key

  • Author and year

  • Full formatted citation on hover

✅ Quick Citation Commands

CommandDescription
scimax.ref.insertCitationC-c - ]Insert/append citation
scimax.ref.insertRefC-u C-c ]Insert cross-reference (ref:, eqref:)
scimax.ref.insertBibliographyInsert bibliography link

✅ Insert from Zotero

Scimax can insert citations directly from your Zotero library using the Better BibTeX plugin. This provides seamless integration between your Zotero reference manager and org-mode documents.

✅ Requirements

To use Zotero integration, you need:

  1. Zotero desktop application - Must be running when inserting citations

  2. Better BibTeX plugin - Install from https://retorque.rezotero-better-bibtex

Better BibTeX provides the local API that Scimax uses to communicate with Zotero.

✅ Usage

KeybindingCommandDescription
C-c zscimax.zotero.insertCitationInsert citation from Zotero

✅ Workflow

  1. Press C-c z in an org, markdown, or LaTeX file

  2. Zotero's native citation picker opens (you may need to switch to the Zotero window)

  3. Search and select one or more references

  4. Click "OK" or press Enter to confirm your selection

  5. The citation is inserted at the cursor position

  6. The BibTeX entry is automatically added to your bibliography file

✅ Bibliography File Handling

When inserting from Zotero, the extension intelligently manages your bibliography file:

ScenarioBehavior
Document has bibliography: linkUses that file
No link, but references.bib exists in dirAsks if you want to use it
No link, no references.bibCreates references.bib and adds bibliography link

The extension automatically:

  • Avoids adding duplicate entries (checks by citation key)

  • Preserves the original BibTeX formatting from Zotero/Better BibTeX

  • Adds a bibliography: link at the end of the document if needed

✅ Example

Before (no bibliography):

,* My Research Paper

Some text discussing machine learning.

After pressing C-c z and selecting a reference:

,* My Research Paper

Some text discussing machine learning cite:&smith2024machine.

bibliography:./references.bib

✅ Troubleshooting

ProblemSolution
"Zotero is not running"Start Zotero desktop application
Picker doesn't appearSwitch to Zotero window; it may be behind VS Code
"Failed to fetch BibTeX"Ensure Better BibTeX is installed and enabled
Wrong citation formatCheck scimax.ref.citationSyntax setting (v2 vs v3)
VS Code loses focus after insertThis is an OS limitation; manually switch back to VS Code

Citation Manipulation

When cursor is on a citation with multiple keys:

Transpose Citations

KeyCommandAction
S- Arrowscimax.ref.transposeCitationLeftSwap with previous key
S- Arrowscimax.ref.transposeCitationRightSwap with next key

Example:

cite:jones2023,smith2024,doe2022
       ^cursor here

Press S-<right>:
cite:jones2023,doe2022,smith2024
                      ^cursor follows

Sort Citations

KeyCommandAction
S- Arrowscimax.ref.sortCitationsSort by year (oldest first)
S-scimax.ref.sortCitationsByYearSort by year (newest first)
scimax.ref.sortCitationsAlphabeticallySort alphabetically by key

Citations are sorted by extracting year from:

  1. Bibliography entry year field

  2. Year pattern in citation key (e.g., smith-2024-machine)

Delete Citation Key

CommandAction
scimax.ref.deleteCitationDelete current key or entire citation

  • If multiple keys: Removes current key only

  • If single key: Deletes entire citation

Bibliography Display

References Tree View

The References view shows your bibliography organized by entry type:

REFERENCES
├─ article (45)
│  ├─ smith2024machine: Smith (2024)
│  ├─ jones2023deep: Jones (2023)
│  └─ ...
├─ book (12)
│  ├─ doe2022python: Doe (2022)
│  └─ ...
└─ inproceedings (23)
   └─ ...

Click an entry to open the action menu.

Search References

CommandDescription
scimax.ref.searchReferencesSearch bibliography by author/title/year

Searches across:

  • Citation keys

  • Author names

  • Titles

  • Years

  • Journals

  • Keywords

Results are ranked by relevance (key matches first, then author, then title).

Find Citations

CommandDescription
scimax.ref.findCitationsFind all citations of a reference

Searches workspace for citations of a selected key in all org, markdown, and LaTeX files. Results shown in peek view for quick navigation.

Fetching References from DOI

Add Reference from DOI

CommandDescription
scimax.ref.fetchFromDOIFetch BibTeX entry from DOI via CrossRef

Usage

  1. Run scimax.ref.fetchFromDOI

  2. Enter DOI (accepts 10.xxxxxx or https:doi.org10.xxx/xxx)

  3. Preview the fetched entry

  4. Choose action:

DOI Resolution

The system fetches metadata from CrossRef API and converts it to BibTeX format. If the key already exists, you can:

  • Replace the existing entry

  • Generate a new unique key

  • Cancel

Search CrossRef by Query

CommandDescription
scimax.ref.searchCrossRefSearch CrossRef and add entry by query

When you don't have a DOI, you can search CrossRef directly by title, author, or keywords:

  1. Run scimax.ref.searchCrossRef

  2. Enter search query (or select text first to pre-fill)

  3. Browse results showing title, authors, year, publisher, and DOI

  4. Select an entry to add

  5. Confirm to add to bibliography

This is useful when:

  • You have a paper title but not its DOI

  • You want to find papers by a specific author

  • You remember keywords but not the exact citation

If you have text selected when running the command, it will be used as the initial search query.

OpenAlex Integration

OpenAlex provides enhanced metadata for academic works:

Show Citing Works

CommandDescription
scimax.ref.showCitingWorksShow papers citing this work

Displays papers that cite the selected reference with:

  • Title, authors, year

  • Citation count

  • Open Access status and PDF link

  • Publication venue

Search OpenAlex

CommandDescription
scimax.ref.searchOpenAlexSearch OpenAlex database

Search the global OpenAlex database for works by title, author, or keywords. Results include:

  • Citation counts

  • Open Access status

  • Topic classification

  • Abstracts

DOI Hover Information

Hover over DOI links (doi:10.xxx, https:/doi.org10.xxx) to see:

  • Title, authors, publication info

  • Citation count (via OpenAlex)

  • Open Access status and PDF link

  • Abstract

  • Quick actions: Add to bibliography, open DOI, view citing works

Cross-References

Beyond citations, Scimax supports cross-references to figures, tables, equations, and sections.

Insert Cross-Reference

KeyCommand
C-S-]Insert ref (scimax.ref.insertRef)

  1. Run scimax.ref.insertRef

  2. Select label from workspace

  3. Choose reference type (ref, eqref, pageref, etc.)

  4. Reference inserted at cursor

Label Definitions

Define labels for cross-referencing. The ref: link type searches for these label definitions:

Definition TypeSyntaxExample
#+NAME:#+NAME: labelTables, figures, blocks
#+LABEL:#+LABEL: labelFigures, tables
label:label:labelInline labels
\label{}\label{label}LaTeX labels
:CUSTOMID::CUSTOM_ID: labelHeading IDs

Org-Mode Labels

,#+NAME: fig-results
,#+CAPTION: Experimental results
[[file:./images/results.png]]

,#+NAME: tbl-data
,#+CAPTION: Data summary
| Column 1 | Column 2 |
|----------+----------|
| Data     | Values   |

label:eq-main  \[ E = mc^2 \]

,* Methods
:PROPERTIES:
:CUSTOM_ID: methods
:END:

References:

See ref:fig-results for the results.
See ref:tbl-data for the data summary.
As shown in eqref:eq-main, energy equals...
The ref:methods section describes our approach.

LaTeX Labels

\begin{equation}
  \label{eq:main}
  E = mc^2
\end{equation}

See equation \eqref{eq:main} for details.

Reference Hover

Hover over cross-references to see:

  • Label type (figure, table, equation, heading)

  • Caption or heading text

  • Surrounding context

  • Link to jump to definition

Export of Citations

HTML Export

HTML export uses citation-js for full CSL-based citation formatting. Citations are processed according to standard citation styles like APA, MLA, Chicago, etc.

Specifying Citation Style

Use #+CSL_STYLE: to set the citation format:

#+CSL_STYLE: apa

Available styles: apa (default), mla, chicago, harvard, ieee, vancouver

Bibliography Generation

The HTML export automatically generates a formatted bibliography section at the end of the document. Ensure your document includes a bibliography reference:

#+BIBLIOGRAPHY: references.bib

See Export System: HTML Citation Export for complete documentation.

LaTeX Export

Citations convert to LaTeX commands:

Org CitationLaTeX Output
(key)\cite{key}
key\citet{key}
(key)\citep{key}
key\citeauthor{key}
(key)\citeyear{key}

Bibliography links export to \bibliography{file} commands.

Markdown Export

Citations export to Pandoc citation syntax:

Org CitationPandoc Markdown Output
(key)[@key]
key@key
(key)[@key]

Extract Bibliography for Document

CommandDescription
scimax.ref.extractBibliographyExtract cited references to new .bib file

Useful for creating document-specific bibliography files:

  1. Scans current document for all citations

  2. Looks up entries in your bibliography

  3. Saves to new .bib file or copies to clipboard

Generates a portable .bib file containing only the references cited in your document.

Managing Your Bibliography

Opening Bibliography Files

CommandDescription
scimax.ref.openBibliographyOpen configured bibliography file

If multiple files configured, shows a picker.

Copy BibTeX Entry

CommandDescription
scimax.ref.copyBibTeXCopy BibTeX entry for selected reference

Select a reference and copy its BibTeX source to clipboard.

Refresh Bibliography

CommandDescription
scimax.ref.refreshReload all bibliography files

Reloads all configured and workspace .bib files. Useful after external changes.

Bibliography File Diagnostics

The extension validates bibliography links in org files:

  • Highlights missing bibliography files

  • Shows error diagnostics for invalid paths

  • Suggests creating missing files

Code Lenses in .bib Files

When viewing a .bib file, code lenses appear for each entry:

  • Find citations - Search workspace for citations of this key

  • Copy key - Copy citation key to clipboard

Command Reference

Citation Commands

CommandDefault KeyDescription
scimax.ref.insertCitationC-c ]Insert/append citation
scimax.zotero.insertCitationC-c zInsert citation from Zotero
scimax.ref.insertRefC-S-]Insert cross-reference
scimax.ref.insertBibliographyInsert bibliography link
scimax.ref.transposeCitationLeftS-Swap citation left
scimax.ref.transposeCitationRightS-Swap citation right
scimax.ref.sortCitationsS-Sort by year ascending
scimax.ref.sortCitationsByYearS-Sort by year descending
scimax.ref.sortCitationsAlphabeticallySort alphabetically
scimax.ref.deleteCitationDelete citation key

Bibliography Commands

CommandDescription
scimax.ref.openBibliographyOpen bibliography file
scimax.ref.searchReferencesSearch bibliography
scimax.ref.findCitationsFind citations of reference
scimax.ref.copyBibTeXCopy BibTeX entry
scimax.ref.refreshReload bibliography files
scimax.ref.extractBibliographyExtract cited references

DOI and External Commands

CommandDescription
scimax.ref.fetchFromDOIAdd reference from DOI
scimax.ref.searchCrossRefSearch CrossRef and add entry
scimax.ref.showCitingWorksShow citing works (OpenAlex)
scimax.ref.showRelatedWorksShow related works (OpenAlex)
scimax.ref.searchOpenAlexSearch OpenAlex database

Best Practices

Organizing Your Bibliography

Use Consistent Citation Keys

Good key format: author-year-keyword

Examples:

  • smith-2024-machine-learning

  • jones-2023-deep-neural

  • doe-2022-python-scientific

Benefits:

  • Easy to remember and type

  • Sorting by name is meaningful

  • Year visible in key

  • Keyword aids recall

Maintain Multiple .bib Files

Organize by topic or project:

~/Documents/
├── machine-learning.bib      # ML papers
├── statistics.bib             # Statistics references
└── projects/
    └── thesis/
        └── thesis-refs.bib    # Thesis-specific

Configure global files + use document-local links for project-specific references.

Store PDFs Systematically

Use consistent naming in PDF directory:

  • smith-2024-machine-learning.pdf

  • Match citation keys when possible

  • Or use FirstAuthorYear.pdf format

Citation Workflow

Literature Review Workflow

  1. Search OpenAlex: scimax.ref.searchOpenAlex

  2. Find relevant paper

  3. Add to bibliography via DOI

  4. Check citing works: scimax.ref.showCitingWorks

  5. Explore related works: scimax.ref.showRelatedWorks

  6. Create notes file for each key reference

  7. Download PDFs to configured directory

Writing Workflow

  1. Write draft with placeholder citations

  2. Insert citations: C-c ]

  3. Search references interactively

  4. Hover citations to verify

  5. Before final export: scimax.ref.extractBibliography

  6. Creates portable .bib file with your document

Managing Notes

Create comprehensive notes for key papers:

,#+TITLE: Notes on Smith (2024) - Machine Learning
,#+CITE_KEY: smith2024machine

,* Summary
Three-sentence summary of the paper

,* Key Points
- Main contribution 1
- Main contribution 2
- Methodology highlights

,* Quotes
,#+BEGIN_QUOTE
"Important quote from the paper" (p. 42)
,#+END_QUOTE

,* Personal Notes
Connections to my research...

,* Follow-up References
- cite:jones2023deep - Related deep learning work
- cite:nguyen2024neural - Extends their methodology

Link notes from your main document:

Recent work on machine learning cite:smith2024machine (see also [[file:~/notes/smith2024machine.org][my notes]])

Export Considerations

For LaTeX/PDF Export

Ensure bibliography link includes all cited .bib files:

bibliography:~/Documents/refs.bib,./local-refs.bib

Use standard citation styles LaTeX understands (cite, citet, citep).

For HTML Export

Citations export as links. For proper bibliography rendering:

  1. Ensure #+BIBLIOGRAPHY: keyword is present

  2. Or include bibliography: link

  3. HTML export generates bibliography section automatically

For Standalone Documents

Before sharing:

  1. Run scimax.ref.extractBibliography

  2. Save extracted .bib alongside document

  3. Update bibliography link to local file:

BibTeX Entry Quality

Ensure complete entries for best results:

@article{key,
  author = {Required},
  title = {Required},
  journal = {Recommended for articles},
  year = {Required},
  volume = {Recommended},
  number = {Recommended},
  pages = {Recommended},
  doi = {Highly recommended - enables OpenAlex integration},
  url = {Useful if no DOI},
  abstract = {Helpful for hover info},
  keywords = {Aids search}
}

Troubleshooting

Citation Not Found

If citation shows "not found in bibliography":

  1. Check spelling of citation key

  2. Verify .bib file is configured or linked in document

  3. Run `scimax.ref.refresh' to reload bibliography

  4. Check .bib file for entry with that exact key

PDF Not Found

If "PDF not found" when trying to open:

  1. Check `scimax.ref.pdfDirectory' is set correctly

  2. Verify PDF filename matches key or Author_Year.pdf pattern

  3. Check file exists with `ls' or file explorer

  4. Try opening from DOI if available

DOI Fetch Fails

If fetching from DOI fails:

  1. Verify DOI is correct (should start with 10.)

  2. Check internet connection

  3. Try searching on https://crossref.org directly

  4. Some DOIs may not be in CrossRef database

  5. Try OpenAlex search as alternative

Export Issues

If citations don't export correctly:

  1. Check export format supports citations

  2. Verify bibliography link is present in document

  3. Ensure citation keys are in bibliography

  4. For LaTeX: check LaTeX citation package is available

  5. For Pandoc: use Pandoc-compatible citation syntax

Quick Reference Card

Essential Keybindings

KeyAction
C-c ]Insert citation
C-c zInsert citation from Zotero
C-S-]Insert cross-reference
C-c C-oOpen link/citation at point
S-Transpose citation left
S-Transpose citation right
S-Sort citations (oldest first)
S-Sort citations (newest first)

Citation Syntax Quick Reference

FormatOrg-ModeMarkdownLaTeX
Basic(key)[@key]\cite{key}
Textualkey@key\citet{key}
Parenthetical(key)[@key]\citep{key}
Author onlykeyN/A\citeauthor{key}
Year only(key)N/A\citeyear{key}
Multiple(k1, k2, k3)[@k1; @k2]\cite{k1,k2,k3}

Common Workflows

Add New Reference

  1. scimax.ref.fetchFromDOI or scimax.ref.searchOpenAlex

  2. Review metadata

  3. Add to bibliography

Insert Citation

  1. C-c ]

  2. Search for reference

  3. Select citation style

  4. Citation inserted

Prepare for Export

  1. scimax.ref.extractBibliography

  2. Save to document directory

  3. Update bibliography link

  4. Export document

Navigation