Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
981ab2d
Add Velocity-based export format (first iteration for #12418)
koppor Jul 19, 2026
8a24fcd
Address CHECKLIST.md items: NullMarked, l10n, requirement doc
koppor Jul 19, 2026
29e454e
Add daily workflow merging feature branches into all-branches-merged
Jul 27, 2026
3c408ba
Merge directory-rest-api from JabRef/jabref
Jul 27, 2026
15de89d
Note why merge-all-branches.yml must stay on the default branch
koppor Jul 27, 2026
456ce7a
Merge into experimental instead of all-branches-merged
koppor Jul 27, 2026
0183b58
Rename workflow to update-experimental
koppor Jul 27, 2026
0344416
Merge add-comments-tab and re-run when the branch list changes
koppor Jul 27, 2026
625bbc6
Merge branch 'JabRef:main' into main
calixtus Jul 27, 2026
f1d4df3
Merge branch 'JabRef:main' into main
koppor Jul 29, 2026
e9a7aab
Remove merged zotero-item-import-endpoint from experimental branch list
koppor Jul 29, 2026
1dd5a3c
Drop add-comments-tab from the experimental branch list
koppor Aug 3, 2026
7d96263
Merge branch 'JabRef:main' into main
koppor Aug 18, 2026
ad09065
Use PAT
koppor Aug 23, 2026
df58d8e
Add fixUnlinkedFiles (PR #16696) to experimental merge
koppor Aug 28, 2026
87678d8
Update update-experimental.yml
koppor Aug 28, 2026
bd86efc
Add common-style (PR #16708) to experimental merge
koppor Aug 31, 2026
fe9f386
Drop merged/closed branches from experimental merge list
koppor Aug 31, 2026
7185d04
Merge remote-tracking branch 'origin/main' into koppor-main-sync
koppor Sep 3, 2026
fcba284
Merge branch 'JabRef:main' into main
koppor Sep 3, 2026
bbbefa4
Add fulltext-context-menu to the experimental merge list
koppor Sep 3, 2026
9fac562
Update update-experimental.yml
koppor Sep 3, 2026
e8611d0
Add show-diff-button to experimental merge list
koppor Sep 3, 2026
bfaa38b
Merge remote-tracking branch 'origin/main' into HEAD
koppor Sep 3, 2026
c437d5e
Merge remote-tracking branch 'origin/main' into velocity-layouts
claude Sep 3, 2026
e4daa2d
Merge remote-tracking branch 'origin/main' into velocity-layouts
claude Sep 16, 2026
3aff02d
Merge remote-tracking branch 'origin/main' into velocity-layouts
claude Oct 10, 2026
1a1c500
Merge remote-tracking branch 'origin/main' into velocity-layouts
claude Oct 23, 2026
5841097
Merge remote-tracking branch 'origin/main' into velocity-layouts
claude Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv

### Added

- We added a new export format "Simple HTML (Velocity)" (`simplehtml-velocity`), the first export based on the [Apache Velocity](https://velocity.apache.org/) template engine, which will gradually replace the `.layout`-based export format. [#12418](https://github.com/JabRef/jabref/issues/12418)
- We added an option to enable AI provider debugging in expert settings for testing AI features without external API calls. [#17607](https://github.com/JabRef/jabref/pull/17607)
- We added ISBN extraction from bibliographic pages in PDF books. [#12874](https://github.com/JabRef/jabref/issues/12874)
- We added a dark appearance variant of the macOS application icon. [#17290](https://github.com/JabRef/jabref/issues/17290)
Expand Down
12 changes: 12 additions & 0 deletions docs/requirements/export.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,5 +60,17 @@ Local attachments that cannot be resolved or represented relatively are omitted.

Needs: impl, utest

## Exports can be defined as Apache Velocity templates
`req~logic.exporter.velocity-template~1`

An export format can be defined as a single [Apache Velocity](https://velocity.apache.org/) template
(instead of a set of per-entry-type `.layout` files).
The template iterates over the sorted entries (`$entries`); each entry offers its type, citation key,
and field values (with field aliases, BibTeX strings, and `crossref` inheritance resolved) as plain strings,
where an unset field is the empty string.
See [ADR 39](../decisions/0039-use-apache-velocity-as-template-engine.md) for the engine choice.

Needs: impl

<!-- markdownlint-disable-file MD013 MD033 MD041 -->
<!-- markdownlint-disable-file MD022 -->
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,7 @@ public static ExporterFactory create(CliPreferences preferences) {
exporters.add(new TemplateExporter("MIS Quarterly", "misq", "misq", "misq", StandardFileType.RTF, layoutPreferences, saveOrder));
exporters.add(new TemplateExporter("CSL YAML", "yaml", "yaml", "", StandardFileType.YAML, layoutPreferences, saveOrder, BlankLineBehaviour.DELETE_BLANKS));
exporters.add(new TemplateExporter("Hayagriva YAML", "hayagrivayaml", "hayagrivayaml", "", StandardFileType.YAML, layoutPreferences, saveOrder, BlankLineBehaviour.DELETE_BLANKS));
exporters.add(new VelocityTemplateExporter(Localization.lang("Simple HTML (Velocity)"), "simplehtml-velocity", "simplehtml.vm", StandardFileType.HTML, saveOrder));
exporters.add(new OpenOfficeDocumentCreator());
exporters.add(new OpenDocumentSpreadsheetCreator());
exporters.add(new MSBibExporter());
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
package org.jabref.logic.exporter;

import org.jabref.model.database.BibDatabase;
import org.jabref.model.entry.BibEntry;
import org.jabref.model.entry.field.FieldFactory;

import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;

/// Read-only view of a [BibEntry] for use in export templates (see [VelocityTemplateExporter]).
///
/// All accessors return plain strings — the empty string for unset fields — so that templates
/// can rely on Velocity's empty-string check: `#if( $entry.getField("author") ) ... #end`.
@NullMarked
public class TemplateBibEntry {

private final BibEntry entry;
private final @Nullable BibDatabase database;

public TemplateBibEntry(BibEntry entry, @Nullable BibDatabase database) {
this.entry = entry;
this.database = database;
}

/// Usable as `$entry.type` in templates. Standard entry types are lower case (e.g., `article`).
public String getType() {
return entry.getType().getName();
}

/// Usable as `$entry.citationKey` in templates.
public String getCitationKey() {
return entry.getCitationKey().orElse("");
}

/// Returns the value of the given field, resolving field aliases (e.g., `year` from `date`),
/// BibTeX strings, and `crossref` inheritance.
public String getField(String fieldName) {
return entry.getResolvedFieldOrAlias(FieldFactory.parseField(fieldName), database).orElse("");
}
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
package org.jabref.logic.exporter;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.nio.charset.StandardCharsets;
import java.nio.file.Path;
import java.util.List;
import java.util.Optional;

import org.jabref.logic.layout.format.HTMLChars;
import org.jabref.logic.util.FileType;
import org.jabref.model.database.BibDatabaseContext;
import org.jabref.model.entry.BibEntry;
import org.jabref.model.metadata.SelfContainedSaveOrder;

import org.apache.velocity.VelocityContext;
import org.apache.velocity.app.VelocityEngine;
import org.jspecify.annotations.NullMarked;

/// Export format based on an Apache Velocity template — the designated successor of the
/// `.layout`-based [TemplateExporter] (see ADR-0039 and [#12418](https://github.com/JabRef/jabref/issues/12418)).
///
/// In contrast to the `.layout` format (separate begin/entry/end files, one per entry type),
/// a Velocity export is a single template iterating over `$entries`, e.g.
/// `#foreach( $entry in $entries )$entry.type: $html.format($entry.getField("title"))
/// #end`.
///
/// Context contract (see [TemplateBibEntry] for the entry view):
/// - `$entries` — the sorted entries to export
/// - `$html` — [HTMLChars], converts LaTeX markup to HTML (`$html.format(...)`)
// [impl->req~logic.exporter.velocity-template~1]
@NullMarked
public class VelocityTemplateExporter extends Exporter {

static final String TEMPLATE_PREFIX = "/resource/template/";

private static final VelocityEngine VELOCITY_ENGINE = new VelocityEngine();

static {
VELOCITY_ENGINE.init();
}

private final String templateFileName;
private final SelfContainedSaveOrder saveOrder;

/// @param templateFileName name of the template resource below `/resource/template/`, e.g. `simplehtml.vm`
public VelocityTemplateExporter(String displayName,
String consoleName,
String templateFileName,
FileType extension,
SelfContainedSaveOrder saveOrder) {
super(consoleName, displayName, extension);
this.templateFileName = templateFileName;
this.saveOrder = saveOrder;
}

@Override
public void export(BibDatabaseContext databaseContext,
Path file,
List<BibEntry> entries) throws IOException {
if (entries.isEmpty()) { // Do not export if no entries to export -- avoids exports with only template text
return;
}

List<TemplateBibEntry> templateEntries = BibDatabaseWriter.getSortedEntries(entries, saveOrder)
.stream()
.map(entry -> new TemplateBibEntry(entry, databaseContext.getDatabase()))
.toList();

VelocityContext context = new VelocityContext();
context.put("entries", templateEntries);
context.put("html", new HTMLChars());

InputStream inputStream = Optional.ofNullable(VelocityTemplateExporter.class.getResourceAsStream(TEMPLATE_PREFIX + templateFileName))
.orElseThrow(() -> new IOException("Cannot find template file: '" + TEMPLATE_PREFIX + templateFileName + "'."));
try (AtomicFileWriter writer = new AtomicFileWriter(file, StandardCharsets.UTF_8);
Reader template = new BufferedReader(new InputStreamReader(inputStream, StandardCharsets.UTF_8))) {
VELOCITY_ENGINE.evaluate(context, writer, templateFileName, template);
}
}
}
2 changes: 2 additions & 0 deletions jablib/src/main/resources/l10n/JabRef_en.properties
Original file line number Diff line number Diff line change
Expand Up @@ -968,6 +968,8 @@ Show\ validation\ messages=Show validation messages

Simple\ HTML=Simple HTML

Simple\ HTML\ (Velocity)=Simple HTML (Velocity)

Size=Size

JabRef\ skipped\ the\ entry.=JabRef skipped the entry.
Expand Down
38 changes: 38 additions & 0 deletions jablib/src/main/resources/resource/template/simplehtml.vm
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
<!DOCTYPE HTML>
<html>
<head>
<title>JabRef references</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<style type="text/css">
body { font-size: 12px; font-family: Arial, sans-serif; }
dt { margin-top: 1em; font-weight: bold; }
@media print {
dt { page-break-after: avoid; }
dd { page-break-before: avoid; }
}
</style>
</head>
<body>
<dl>
#foreach( $entry in $entries )
<dt>$entry.type #if( $entry.citationKey )<a name="$entry.citationKey">($entry.citationKey)</a>#end</dt>
#if( $entry.getField("author") )
<dd>$html.format($entry.getField("author"))</dd>
#end
#if( $entry.getField("title") )
<dd><i>$html.format($entry.getField("title"))</i></dd>
#end
#if( $entry.getField("editor") )
<dd>$html.format($entry.getField("editor")) <i>(ed.)</i></dd>
#end
#if( $entry.getField("booktitle") )
<dd>$html.format($entry.getField("booktitle"))</dd>
#end
#if( $entry.getField("chapter") )
<dd>Chapter $html.format($entry.getField("chapter"))</dd>
#end
<dd>#if( $entry.getField("journal") )$html.format($entry.getField("journal")), #end#if( $entry.getField("school") )$html.format($entry.getField("school")), #end#if( $entry.getField("publisher") )$html.format($entry.getField("publisher")), #end#if( $entry.getField("year") )<b>$entry.getField("year")</b>#end#if( $entry.getField("volume") ), Vol. $entry.getField("volume")#end#if( $entry.getField("number") )($entry.getField("number"))#end#if( $entry.getField("pages") ), pp. $entry.getField("pages")#end</dd>
#end
</dl>
</body>
</html>
Original file line number Diff line number Diff line change
@@ -0,0 +1,145 @@
package org.jabref.logic.exporter;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.ArrayList;
import java.util.List;

import org.jabref.logic.util.StandardFileType;
import org.jabref.model.database.BibDatabaseContext;
import org.jabref.model.entry.BibEntry;
import org.jabref.model.entry.field.StandardField;
import org.jabref.model.entry.types.StandardEntryType;
import org.jabref.model.metadata.SaveOrder;

import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;

import static org.junit.jupiter.api.Assertions.assertEquals;

class VelocityTemplateExporterTest {

private static final List<String> HTML_HEAD = List.of(
"<!DOCTYPE HTML>",
"<html>",
"<head>",
"<title>JabRef references</title>",
"<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\">",
"<style type=\"text/css\">",
"body { font-size: 12px; font-family: Arial, sans-serif; }",
"dt { margin-top: 1em; font-weight: bold; }",
"@media print {",
"\tdt { page-break-after: avoid; }",
"\tdd { page-break-before: avoid; }",
"}",
"</style>",
"</head>",
"<body>",
"<dl>");

private static final List<String> HTML_FOOT = List.of(
"</dl>",
"</body>",
"</html>");

private static VelocityTemplateExporter exporter;
private static BibDatabaseContext databaseContext;

@BeforeAll
static void setUp() {
exporter = new VelocityTemplateExporter(
"Simple HTML (Velocity)",
"simplehtml-velocity",
"simplehtml.vm",
StandardFileType.HTML,
SaveOrder.getDefaultSaveOrder());
databaseContext = new BibDatabaseContext();
}

private static List<String> expectedOutput(String... entryLines) {
List<String> result = new ArrayList<>(HTML_HEAD);
result.addAll(List.of(entryLines));
result.addAll(HTML_FOOT);
return result;
}

@Test
void exportForNoEntriesWritesNothing(@TempDir Path tempDir) throws IOException {
Path file = tempDir.resolve("ThisIsARandomlyNamedFile");
Files.createFile(file);
exporter.export(databaseContext, file, List.of());
assertEquals(List.of(), Files.readAllLines(file));
}

@Test
void exportsCorrectContent(@TempDir Path tempDir) throws IOException {
BibEntry entry = new BibEntry(StandardEntryType.Article)
.withCitationKey("test")
.withField(StandardField.AUTHOR, "Test Author")
.withField(StandardField.TITLE, "Test Title")
.withField(StandardField.JOURNAL, "Test Journal")
.withField(StandardField.YEAR, "2020")
.withField(StandardField.VOLUME, "1")
.withField(StandardField.NUMBER, "2")
.withField(StandardField.PAGES, "11--22");

Path file = tempDir.resolve("RandomFileName");
Files.createFile(file);
exporter.export(databaseContext, file, List.of(entry));

assertEquals(expectedOutput(
"<dt>article <a name=\"test\">(test)</a></dt>",
"<dd>Test Author</dd>",
"<dd><i>Test Title</i></dd>",
"<dd>Test Journal, <b>2020</b>, Vol. 1(2), pp. 11--22</dd>"),
Files.readAllLines(file));
}

@Test
void convertsLatexMarkupToHtml(@TempDir Path tempDir) throws IOException {
BibEntry entry = new BibEntry(StandardEntryType.Book)
.withCitationKey("goedel")
.withField(StandardField.AUTHOR, "Kurt G{\\\"o}del")
.withField(StandardField.TITLE, "Some {\\emph{Deep}} Thoughts")
.withField(StandardField.PUBLISHER, "Test Publisher")
.withField(StandardField.YEAR, "1931");

Path file = tempDir.resolve("RandomFileName");
Files.createFile(file);
exporter.export(databaseContext, file, List.of(entry));

assertEquals(expectedOutput(
"<dt>book <a name=\"goedel\">(goedel)</a></dt>",
"<dd>Kurt G&ouml;del</dd>",
"<dd><i>Some <em>Deep</em> Thoughts</i></dd>",
"<dd>Test Publisher, <b>1931</b></dd>"),
Files.readAllLines(file));
}

@Test
void exportsMultipleEntries(@TempDir Path tempDir) throws IOException {
BibEntry first = new BibEntry(StandardEntryType.Article)
.withCitationKey("first")
.withField(StandardField.TITLE, "First Title")
.withField(StandardField.YEAR, "2020");
BibEntry second = new BibEntry(StandardEntryType.Article)
.withCitationKey("second")
.withField(StandardField.TITLE, "Second Title")
.withField(StandardField.YEAR, "2021");

Path file = tempDir.resolve("RandomFileName");
Files.createFile(file);
exporter.export(databaseContext, file, List.of(first, second));

assertEquals(expectedOutput(
"<dt>article <a name=\"first\">(first)</a></dt>",
"<dd><i>First Title</i></dd>",
"<dd><b>2020</b></dd>",
"<dt>article <a name=\"second\">(second)</a></dt>",
"<dd><i>Second Title</i></dd>",
"<dd><b>2021</b></dd>"),
Files.readAllLines(file));
}
}
Loading