https://github.com/notzaki/pandocciter
Visual Studio Code extension for autocompleting citations and cross-references for Pandoc/Markdown documents
https://github.com/notzaki/pandocciter
bibtex markdown pandoc pandoc-crossref vscode vscode-extension
Last synced: 14 days ago
JSON representation
Visual Studio Code extension for autocompleting citations and cross-references for Pandoc/Markdown documents
- Host: GitHub
- URL: https://github.com/notzaki/pandocciter
- Owner: notZaki
- License: mit
- Created: 2018-08-06T19:00:58.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2024-06-21T10:08:01.000Z (11 months ago)
- Last Synced: 2025-04-22T22:18:54.262Z (14 days ago)
- Topics: bibtex, markdown, pandoc, pandoc-crossref, vscode, vscode-extension
- Language: TypeScript
- Homepage: https://marketplace.visualstudio.com/items?itemName=notZaki.pandocciter
- Size: 359 KB
- Stars: 68
- Watchers: 3
- Forks: 11
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Pandoc Citer Extension for Visual Studio Code
This extension provides autocompletion of citations stored in a bibtex file, for use with [pandoc-markdown](https://pandoc.org/) documents, along with auto-completion for [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) cross-references.
## Features
### Autocomplete citations
- Citations follow the standard syntax recognized by [pandoc-citeproc](https://github.com/jgm/pandoc-citeproc), i.e.:
- Citation syntax: `@BibKey` or `[@bibKey]`
+ Typing '@' should automatically trigger the suggestion window to show up. If not, try `Ctrl + Space`.
+ The suggestion window (probably) won't trigger if the `@` is right after some text without a space, i.e. `text@` won't trigger the suggestions but `text @` will. This restriction was made so that typing an email address won't trigger the citation suggestions.
- The YAML should contain the line
```
bibliography: [path/to/.bib]
```
- The path/to/.bib can either be a single path, a list of paths enclosed by square brackets, or a bullet list of paths
- The path/to/.bib can be either a relative or absolute path
- Multiple bib files can be included if separated by comma, e.g. `[path/to/refsA.bib, path/to/refsB.bib]`
## Configuration
- `PandocCiter.CrossRefMode`
+ Type: String, either "full" (default), "minimal", or "none"
+ Function: This changes the detail shown during auto-completion of cross-references. Setting this to "none" will disable auto-completion of pandoc-crossref references.
- `PandocCiter.ViewType`
+ Type: String, either "inline" (default) or "browser"
+ Function: Changes how the suggested citations are shown
- `PandocCiter.RootFile`
+ Type: String, path to markdown file
+ Function: This is useful if there are multiple markdown files with one external master file containing the YAML header with the `bibliography: [path/to/bib]` entry. This avoids having to insert the bibliography YAML header into each individual file.
- `PandocCiter.DefaultBibs`
+ Type: Array of Strings, absolute or relative path to bib file
- Note: For relative paths, it will be assumed that the path is relative to the workspace folder
+ Function: This is useful if there is a default bib file that is preferred for all projects. This bib file will be loaded regardless of whether or not a YAML entry is included.
- `PandocCiter.DefaultBib`
+ Same as `PandocCiter.DefaultBibs`, except this is older and only accepts a single path as a string. Not recommended for new users. This only exists to avoid breaking older setups.
- `PandocCiter.UseDefaultBib`
+ Type: Boolean, default is `true`
+ Function: This should be a project-specific setting. It is useful when a DefaultBib is defined but you don't want it to be used for a specific project.
- `PandocCiter.ForgetUnusedBib`
+ Type: Boolean, default is `true`
+ Function: This will check if the bibliography YAML matches the watched bib files, and if any watched files are not in the YAML, then their suggestions will be removed.
+ For example, suppose two markdown files are opened but only one of them has a bibliography entry in their YAML header. If this config is set to `false`, then both markdown files will show citation suggestions. If this config is set to `true`, then citation suggestions will only be shown in the file with the bibliography YAML.
- `PandocCiter.ShowLog`
+ Type: Boolean, default is `false`
+ Function: This will show a log in the Output panel, useful for answering questions like "Why isn't the extension finding my bib file?". The Output panel can be accessed via `VSCode Top Menubar -> View -> Output` which will open a panel at the bottom. Select `PandocCiter` from the drop down list, and the extension's log should show up.
- `PandocCiter.CitationFormat`
+ Type: String array
+ Function: Controls which bibtex fields will be shown in the suggestions window. These items will also be used to filter the suggestions during autocompletion.
## Acknowledgements
- This extension started out as a a stripped down version of the [LaTeX-Workshop extension](https://github.com/James-Yu/LaTeX-Workshop) that has been adjusted for markdown/pandoc
+ The structure of the `src` directory was preserved, so that any updates/fixes here could also be ported to LaTex-Workshop, and vice versa
- Contributors:
- [@smartens](https://github.com/smartens) - fixing bugs
- [@yarray](https://github.com/yarray) - adding pandoc-crossref support
- [@Dominic-DallOsto](https://github.com/Dominic-DallOsto) - adding hover and go-to-definition support
- [@MaxChang3](https://github.com/MaxChang3) - improving hover support