codemirror-lang-bib

CodeMirror 6 BibTeX Language Support

This package provides BibTeX language support for the CodeMirror 6 code editor, designed to work with academic writing workflows and bibliography management.

Features

• BibTeX syntax highlighting with distinct colors for entry types, field names, and values
• Auto-indentation for entries and field values
• Code folding for entries and nested structures
• Bracket matching for braces and quotes
• Autocompletion for:
  • Entry types (@article, @book, @inproceedings, etc.)
  • Field names (author, title, journal, etc.)
  • Common values (month abbreviations, journal names)
• Snippets for common BibTeX entry structures
• Hover tooltips with:
  • Entry type descriptions and requirements
  • Field descriptions and examples
  • Required vs. optional field information
• BibTeX-specific linting:
  • Missing required fields
  • Unknown field names
  • Duplicate citation keys
  • Syntax validation
  • Unmatched braces

Installation

npm install codemirror-lang-bib

Usage

import { EditorState, EditorView } from '@codemirror/basic-setup';
import { bibtex } from 'codemirror-lang-bib';

let editor = new EditorView({
  state: EditorState.create({
    doc: `@article{sample2023,
  author = {John Doe and Jane Smith},
  title = {A Sample Article},
  journal = {Journal of Examples},
  year = {2023},
  volume = {42},
  pages = {123--145}
}`,
    extensions: [
      // ... other extensions
      bibtex()
    ]
  }),
  parent: document.querySelector('#editor')
});

Configuration Options

You can configure the BibTeX language support by passing options:

import { bibtex } from 'codemirror-lang-bib';

// With all options explicitly set (these are the defaults)
const extensions = [
  // ... other extensions
  bibtex({
    enableLinting: true,      // Enable linting
    enableTooltips: true,     // Enable hover tooltips
    enableAutocomplete: true, // Enable autocompletion
    autoCloseBrackets: true   // Enable auto-close brackets
  })
];

API

bibtex()

The main function that creates a LanguageSupport instance for BibTeX.

import { bibtex } from 'codemirror-lang-bib';

// Include BibTeX support in your editor with default options
const extensions = [
  // ... other extensions
  bibtex()
];

// Or with specific options
const extensions = [
  // ... other extensions
  bibtex({
    enableLinting: true,      // Enable linting
    enableTooltips: true,     // Enable tooltips on hover
    enableAutocomplete: true, // Enable autocompletion
    autoCloseBrackets: true   // Enable auto-close brackets
  })
];

bibtexLanguage

The BibTeX language definition. Usually you'll want to use the bibtex() function instead, but you can access this directly if needed.

import { bibtexLanguage } from 'codemirror-lang-bib';

bibtexHoverTooltip

An extension that shows helpful tooltips when hovering over BibTeX entry types and field names.

import { bibtexHoverTooltip } from 'codemirror-lang-bib';

const extensions = [
  // ... other extensions
  bibtexHoverTooltip
];

bibtexLinter

A linter function that checks for common BibTeX errors and issues.

import { bibtexLinter } from 'codemirror-lang-bib';
import { linter } from '@codemirror/lint';

const extensions = [
  // ... other extensions
  linter(bibtexLinter({
    checkRequiredFields: true,  // Check for missing required fields
    checkUnknownFields: true,   // Check for unknown field names
    checkDuplicateKeys: true,   // Check for duplicate citation keys
    checkFieldSyntax: true,     // Check field value syntax
    checkEntryTypes: true       // Check for valid entry types
  }))
];

snippets

A collection of BibTeX-related snippets for common entry structures.

import { snippets } from 'codemirror-lang-bib';

Styling

The package includes CSS styles for syntax highlighting in dist/bib.css. Import these styles to get the default BibTeX syntax highlighting:

import 'codemirror-lang-bib/dist/bib.css';

You can also customize styles in your own CSS by targeting the specific syntax highlight classes.

Advanced Usage

Custom Extensions

You can compose your own editor with exactly the BibTeX features you need:

import { EditorState, EditorView } from '@codemirror/basic-setup';
import { keymap } from '@codemirror/view';
import { linter } from '@codemirror/lint';
import { 
  bibtexLanguage, 
  bibtexCompletionSource, 
  bibtexBracketMatching, 
  bibtexLinter,
  bibtexHoverTooltip
} from 'codemirror-lang-bib';

// Create an editor with only specific BibTeX features
const editor = new EditorView({
  state: EditorState.create({
    doc: "@article{key,\n  author = {Author},\n  title = {Title}\n}",
    extensions: [
      // Basic CodeMirror setup
      basicSetup,
      
      // Add just the BibTeX language with completion
      new LanguageSupport(bibtexLanguage, [
        bibtexLanguage.data.of({
          autocomplete: bibtexCompletionSource
        })
      ]),
      
      // Add only the extensions you want
      bibtexBracketMatching,
      linter(bibtexLinter()),
      bibtexHoverTooltip,
      
      // Line wrapping is useful for BibTeX editing
      EditorView.lineWrapping
    ]
  }),
  parent: document.querySelector('#editor')
});

Supported Entry Types

The package supports all standard BibTeX entry types:

• @article - Journal articles
• @book - Books
• @inproceedings - Conference papers
• @incollection - Book chapters
• @phdthesis - PhD dissertations
• @mastersthesis - Master's theses
• @techreport - Technical reports
• @manual - Manuals and documentation
• @misc - Miscellaneous entries
• @online - Online resources
• @unpublished - Unpublished works
• @booklet - Booklets
• @proceedings - Conference proceedings

Field Validation

The linter validates field requirements based on entry type:

Required Fields by Entry Type

• @article: author, title, journal, year
• @book: author, title, publisher, year
• @inproceedings: author, title, booktitle, year
• @phdthesis: author, title, school, year
• @misc: title

Common Optional Fields

author, editor, pages, volume, number, series, edition, month, note, address, doi, url, isbn, etc.

Building from Source

git clone https://github.com/texlyre/codemirror-lang-bib.git
cd codemirror-lang-bib
npm install
npm run build

License

MIT License. See LICENSE file for details.