## 1. Project Overview & Quickstart (JabRef/jabref) ## File: README.md # JabRef Bibliography Management [](https://apidia.net/java/JabRef/main) JabRef is an open-source, cross-platform citation and reference management tool. Stay on top of your literature: JabRef helps you to collect and organize sources, find the paper you need and discover the latest research. ## Features JabRef is available free of charge and is actively developed. It supports you in every step of your research work. ### Collect - Search across many online scientific catalogues like CrossRef, Google Scholar, IEEEXplore, INSPIRE-HEP, Medline PubMed, MathSciNet, Springer, arXiv, and zbMATH - Import options for over 15 reference formats - Easily retrieve and link full-text articles - Fetch complete bibliographic information based on ISBN, DOI, PubMed-ID and arXiv-ID - Extract metadata from PDFs - Import new references directly from the browser with one click using the [official browser extension](https://github.com/JabRef/JabRef-Browser-Extension) for [Firefox](https://addons.mozilla.org/en-US/firefox/addon/jabref/?src=external-github), [Chrome](https://chrome.google.com/webstore/detail/jabref-browser-extension/bifehkofibaamoeaopjglfkddgkijdlh), [Edge](https://microsoftedge.microsoft.com/addons/detail/pgkajmkfgbehiomipedjhoddkejohfna), and [Vivaldi](https://chrome.google.com/webstore/detail/jabref-browser-extension/bifehkofibaamoeaopjglfkddgkijdlh) ### Organize - Group your research into hierarchical collections and organize research items based on keywords/tags, search terms, or your manual assignments - Advanced search and filter features - Complete and fix bibliographic data by comparing with curated online catalogs such as Google Scholar, Springer, or MathSciNet - Customizable citation key generator - Customize and add new metadata fields or reference types - Find and merge duplicates - Attach related documents: 20 different kinds of documents supported out of the box, completely customizable and extendable - Automatically rename and move associated documents according to customizable rules - Keep track of what you read: ranking, priority, printed, quality-assured ### Cite - Native BibTeX and BibLaTeX support - Cite-as-you-write functionality for external applications such as Emacs, Kile, LyX, Texmaker, TeXstudio, Vim and WinEdt. - Format references using one of thousands of built-in citation styles or create your own style - Support for Word and LibreOffice/OpenOffice for inserting and formatting citations ### Share - Many built-in export options or create your export format - Library is saved as a simple text file, and thus it is easy to share with others via Dropbox and is version-control friendly - Work in a team: sync the contents of your library via a SQL database ## Installation Fresh development builds are available at [builds.jabref.org](https://builds.jabref.org/main/). The [latest stable release is available at GitHub](https://downloads.jabref.org/). Please see our [Installation Guide](https://docs.jabref.org/installation). ## JabKit JabRef offers a CLI application. You can run it using JBang. We provide details at [`.jbang/README.md`](.jbang/README.md). You can also run JabKit using docker: ```terminal docker run ghcr.io/jabref/jabkit:edge --help ``` ## Bug Reports, Suggestions, Other Feedback [](https://donations.jabref.org) [](https://paypal.me/JabRef) We are thankful for any bug reports or other feedback. If you have ideas for new features you want to be included in JabRef, tell us in [the feature section](http://discourse.jabref.org/c/features) of our forum! If you need support in using JabRef, please read the [user documentation](https://docs.jabref.org/), especially the [frequently asked questions (FAQ)](https://docs.jabref.org/faq) and also take a look at our [community forum](https://discourse.jabref.org/c/help/7). You can use our [GitHub issue tracker](https://github.com/JabRef/jabref/issues) to file bug reports. An explanation of donation possibilities and usage of donations is available at our [donations page](https://donations.jabref.org). ## Contributing Want to be part of a free and open-source project that tens of thousands of researchers use every day? Please take a look at our [guidelines for contributing](CONTRIBUTING.md). ## Building from Source Please see [Building from source](https://docs.jabref.org/installation#building-from-source) for instructions on how to build JabRef from sources. ## Research and Education JabRef welcomes research applied to it. The current list of papers where JabRef helped to enhance science is maintained at . The JabRef team also fosters to use JabRef in Software Engineering training. We offer guidelines for this at . When citing JabRef, please use the following citation: ```bibtex @Article{jabref, author = {Oliver Kopp and Carl Christian Snethlage and Christoph Schwentker}, title = {JabRef: BibTeX-based literature management software}, journal = {TUGboat}, volume = {44}, number = {3}, pages = {441--447}, doi = {10.47397/tb/44-3/tb138kopp-jabref}, issn = {0896-3207}, issue = {138}, year = {2023}, } ``` DOI (also includes [full text](https://tug.org/TUGboat/tb44-3/tb138kopp-jabref.pdf)): [10.47397/tb/44-3/tb138kopp-jabref](https://doi.org/10.47397/tb/44-3/tb138kopp-jabref). ## Sponsoring JabRef development is powered by YourKit Java Profiler [](https://www.yourkit.com/java/profiler/) --- ## File: docs/index.md --- nav_order: 1 layout: home --- # Overview on Developing JabRef This page presents all development information around JabRef. In case you are an end user, please head to the [user documentation](https://docs.jabref.org) or to the [general homepage](https://www.jabref.org) of JabRef. ## Starting point for new developers On the page [Setting up a local workspace](https://devdocs.jabref.org/getting-into-the-code/guidelines-for-setting-up-a-local-workspace), we wrote about the initial steps to get your IDE running. We strongly recommend continuing reading there. After you successfully cloned and build JabRef, you are invited to continue reading here. ## JabRef's development strategy We aim to keep up to high-quality code standards and use code quality tools wherever possible. To ensure high code-quality, * We follow the principles of [Java by Comparison](https://java.by-comparison.com). * We follow the principles of [Effective Java](https://www.oreilly.com/library/view/effective-java-3rd/9780134686097/). * We use [Design Patterns](https://java-design-patterns.com/patterns/) when applicable. * We document our design decisions using the lightweight architectural decision records [MADR](https://adr.github.io/madr/). * Each external pull request is reviewed by at least two [JabRef Core Developers](https://github.com/JabRef/jabref/blob/main/MAINTAINERS). ## Continuous integration JabRef has automatic checks using [GitHub actions](https://github.com/features/actions) in place. One of them is checking for proper formatting of the code. Consistent formatting ensures easier reading of the code. Thus, we ensure that all of JabRef's code follows the same code style. Binaries are created using [gradle](https://gradle.org). In case of an internal pull request, they are uploaded to . These binaries are created without any checks to have them available as quickly as possible, even if the localization or some fetchers are broken. You can fnd the deployment workflow runs at: . ## Branches The [main](https://github.com/JabRef/jabref/tree/main) branch is the main development line ("trunk") and is intended to incorporate fixes and improvements as soon as possible and to move JabRef forward to modern technologies such as the latest Java version. Other branches are used for working on and discussing improvements with the help of [pull requests](https://github.com/JabRef/jabref/pulls). One can see the binaries of each branch at [https://builds.jabref.org/](https://builds.jabref.org). Releases mark milestones and are based on the `main` branch at that point in time. ## How JabRef acquires contributors * We participate in [Hacktoberfest](https://www.hacktoberfest.com). * We participate in [Google Summer of Code](https://developers.google.com/open-source/gsoc/). * We are very happy that JabRef is part of [Software Engineering](https://en.wikipedia.org/wiki/Software_engineering) trainings. Please head to [Teaching](teaching.md) for more information on using JabRef as a teaching object and on previous courses where JabRef was used. ## Next reading Please head to [Architecture and Components](architecture-and-components.md) to read on the high-level architecture and JabRef's (logical) components. --- ## File: docs/README.md # JabRef Developer Documentation The developer documentation is created using the Jekyll Theme [Just the Docs](https://just-the-docs.github.io/just-the-docs/). ## Local Development For local development, follow the [Jekyll installation instructions](https://jekyllrb.com/docs/installation/). Installing the latest version of ruby followed by `gem install bundler` should be enough. Afterwards, run ```shell bundle install jekyll serve --livereload ``` and go to in your browser. On **Windows**, using a dockerized environment is recommended: ```shell docker build . -t jrjekyll docker run -p 4000:4000 -it --rm --volume="C:\git-repositories\jabref\docs":/srv/jekyll jrjekyll jekyll serve -H 0.0.0.0 -t ``` * With Ctrl+C you can stop the server (this is enabled by the `-it` switch). * In case you get errors regarding `Gemfile.lock`, just delete `Gemfile.lock` and rerun. * The current `Dockerfile` is hand-crafted. The [Jekyll Docker image](https://github.com/envygeeks/jekyll-docker#jekyll-docker) did not work end of 2022 (because Ruby was too new). ## Execute linting action You can execute the linting action as if it was executed by GitHub by executing following command. ```shell act --rm --platform ubuntu-latest=fwilhe2/act-runner:latest -W .github/workflows/tests.yml -j "markdown" ``` That command uses [act](https://github.com/nektos/act), which brings GitHub actions execution to the developer machine. ## 2. Official Technical Reference & Guides (JabRef/jabref-website) # JabRef static site A minimal Nuxt static-site project for the JabRef landing page. It uses Vue components and Nuxt static generation, but includes no server routes, database, authentication, GraphQL, or runtime API calls. ## Acknowledgements The Vue implementation is based on the JabRefOnline project, created by [Tobias Diez](https://github.com/TobiasDiez). ## Project layout - `pages/index.vue` contains the landing-page content: hero copy, download and support links, community cards, and the list of feature sections. - `components/FeatureSection.vue` is the reusable Vue component used for each feature row. - `public/assets/` contains the main product images and logo. Files in `public/` are served unchanged below the configured site base path. - `public/img/` contains browser icons and the favicon asset. - `assets/main.css` contains the small site-wide style sheet, including the automatic dark-theme colors. - `assets/legal-notices.html` and `assets/privacy-policy.html` contain the bundled legal text as simple semantic HTML. ## Adding or changing content ### Change page copy or links Edit `pages/index.vue`. The file is organized in the same order as the page: hero, features, download, community, and support. Update an anchor's `href` to change a destination. ### Add a feature 1. Put the feature image in `public/assets/`. 2. Add a `FeatureSection` inside the `#features` section in `pages/index.vue`. 3. Pass its title, image path, and meaningful alternative text. Add `reverse` to place its image on the left on larger screens. Example: ```vue
  • Describe the feature.
    •  ``` ### Add an image Copy an image to `public/assets/` and reference it with `/assets/filename.ext`. The provided `assetUrl()` helper prefixes it with the configured base path; no import or build configuration is needed. ### Create a new page Nuxt creates routes from files in `pages/`: 1. Create a Vue single-file component. For example, `pages/about.vue` becomes `/about`. 2. Add the page content to its `