Added a custom Export for academicpages.github.io

CHANGELOG.md

@@ -21,6 +21,7 @@ Note that this project **does not** adhere to [Semantic Versioning](https://semv
 
 ### Added
 
+- We added another custom Exporter AcademicPagesExporter and a new layout as well as the corresponding line in ExporterFactory. [#12727](...)
 - We added an initial [cite as you write](https://retorque.re/zotero-better-bibtex/citing/cayw/) ("CAYW") endpoint. [#13187](https://github.com/JabRef/jabref/issues/13187)
 - We added a field for the latest ICORE conference ranking lookup on the General Tab. [#13476](https://github.com/JabRef/jabref/issues/13476)
 - We added the option to enable the language server in the preferences. [#13697](https://github.com/JabRef/jabref/pull/13697)

jablib/src/main/java/org/jabref/logic/exporter/AcademicPagesExporter.java

@@ -0,0 +1,124 @@
+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.journals.JournalAbbreviationLoader;
+import org.jabref.logic.journals.JournalAbbreviationRepository;
+import org.jabref.logic.layout.LayoutFormatterPreferences;
+import org.jabref.logic.layout.format.HTMLChars;
+import org.jabref.logic.layout.format.RemoveLatexCommandsFormatter;
+import org.jabref.logic.layout.format.Replace;
+import org.jabref.logic.layout.format.SafeFileName;
+import org.jabref.logic.util.StandardFileType;
+import org.jabref.logic.util.io.FileUtil;
+import org.jabref.model.database.BibDatabaseContext;
+import org.jabref.model.entry.BibEntry;
+import org.jabref.model.metadata.SelfContainedSaveOrder;
+
+import org.jetbrains.annotations.NotNull;
+import org.jspecify.annotations.NonNull;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+/**
+ * A custom exporter to write multiple bib entries as AcademicPages Markdown format.
+ */
+public class AcademicPagesExporter extends Exporter {
+    private static final String BLANK_LINE_PATTERN = "\\r\\n|\\n";
+    private static final String LAYOUT_PREFIX = "/resource/layout/";
+    private static final String LAYOUT_EXTENSION = ".layout";
+    private static final String FORMATTERS_EXTENSION = ".formatters";
+    private static final String BEGIN_INFIX = ".begin";
+    private static final String END_INFIX = ".end";
+
+    private static final Logger LOGGER = LoggerFactory.getLogger(TemplateExporter.class);
+
+    private final String lfFileName;
+    private final String directory;
+    private final LayoutFormatterPreferences layoutPreferences;
+    private final SelfContainedSaveOrder saveOrder;
+    private boolean customExport;
+    private List<BibEntry> entries;
+    private TemplateExporter academicPagesTemplate;
+
+    /**
+     * Initialize another export format based on templates stored in dir with layoutFile lfFilename.
+     *
+     */
+    public AcademicPagesExporter(LayoutFormatterPreferences layoutPreferences, SelfContainedSaveOrder saveOrder) {
+        super("academicpages", "academic pages markdowns", StandardFileType.MARKDOWN);
+        this.lfFileName = "academicpages";
+        this.directory = "academicpages";
+        this.layoutPreferences = layoutPreferences;
+        this.saveOrder = saveOrder;
+        String consoleName = "academicpages";
+        this.academicPagesTemplate = new TemplateExporter("academicpages", consoleName, lfFileName, directory, StandardFileType.MARKDOWN, layoutPreferences, saveOrder);
+    }
+
+    @Override
+    public void export(@NonNull final BibDatabaseContext databaseContext,
+                       final Path exportDirectory,
+                       @NonNull List<BibEntry> entries) throws SaveException {
+        export(databaseContext, exportDirectory, entries, List.of(), JournalAbbreviationLoader.loadBuiltInRepository());
+    }
+
+    /**
+     * The method that performs the export of all entries by iterating on the entries.
+     *
+     * @param databaseContext the database to export from
+     * @param file            the directory to write to
+     * @param entries         a list containing all entries that should be exported
+     * @param abbreviationRepository the built-in repository
+     * @throws SaveException   Exception thrown if saving goes wrong
+     */
+    @Override
+    public void export(@NonNull final BibDatabaseContext databaseContext,
+                       final Path file,
+                       @NonNull List<BibEntry> entries,
+                       List<Path> fileDirForDataBase,
+                       JournalAbbreviationRepository abbreviationRepository) throws SaveException {
+        if (entries.isEmpty()) { // Only export if entries exist
+            return;
+        }
+        try {
+            // convert what the ExportCommand gives as a file parameter to a directory
+            Path baseDir = file;
+            String exportDirectoryString = FileUtil.getBaseName(file);
+            Path exportDirectory = baseDir.getParent().resolve(exportDirectoryString);
+
+            // Ensure the directory exists. This is important: AtomicFileWriter will fail if parent dirs are missing.
+            Files.createDirectories(exportDirectory);
+
+            for (BibEntry entry : entries) {
+                if (entry.getType() == null) {
+                    LOGGER.warn("Skipping entry with no type: {}", entry);
+                    continue;
+                }
+                // formatting the title of each entry to match the file names format demanded by academic pages (applying the same formatters applied to the title in the academicpages.layout)
+                Path path = getPath(entry, exportDirectory);
+
+                List<BibEntry> individual_entry = new ArrayList<BibEntry>();
+                individual_entry.add(entry);
+                academicPagesTemplate.export(databaseContext, path, individual_entry, fileDirForDataBase, abbreviationRepository);
+            }
+        } catch (IOException e) {
+            throw new SaveException("could not export");
+        }
+    }
+
+    private static @NotNull Path getPath(BibEntry entry, Path exportDirectory) {
+        Replace replace_formatter = new Replace();
+        replace_formatter.setArgument(" ,-");
+        RemoveLatexCommandsFormatter commands_formatter = new RemoveLatexCommandsFormatter();
+        HTMLChars html_formatter = new HTMLChars();
+        String title = entry.getTitle().get();
+        String formatted_title = commands_formatter.format(html_formatter.format(replace_formatter.format(title)));
+        SafeFileName safe_formatter = new SafeFileName(); // added custom formatter to remove all characters that are not allowed in filenames
+        String safe_title = safe_formatter.format(formatted_title);
+        return exportDirectory.resolve(safe_title + ".md");
+    }
+}

jablib/src/main/java/org/jabref/logic/exporter/ExporterFactory.java

@@ -63,6 +63,7 @@ public static ExporterFactory create(CliPreferences preferences) {
         exporters.add(new EmbeddedBibFilePdfExporter(bibDatabaseMode, preferences.getCustomEntryTypesRepository(), fieldPreferences));
         exporters.add(new CffExporter());
         exporters.add(new EndnoteXmlExporter(preferences.getBibEntryPreferences()));
+        exporters.add(new AcademicPagesExporter(layoutPreferences, saveOrder));
 
         // Now add custom export formats
         exporters.addAll(customFormats);

jablib/src/main/java/org/jabref/logic/layout/LayoutEntry.java

@@ -66,6 +66,7 @@
 import org.jabref.logic.layout.format.NonSpaceWhitespaceRemover;
 import org.jabref.logic.layout.format.NotFoundFormatter;
 import org.jabref.logic.layout.format.Number;
+import org.jabref.logic.layout.format.NumberMonthFormatter;
 import org.jabref.logic.layout.format.Ordinal;
 import org.jabref.logic.layout.format.RTFChars;
 import org.jabref.logic.layout.format.RemoveBrackets;
@@ -77,6 +78,7 @@
 import org.jabref.logic.layout.format.RisAuthors;
 import org.jabref.logic.layout.format.RisKeywords;
 import org.jabref.logic.layout.format.RisMonth;
+import org.jabref.logic.layout.format.SafeFileName;
 import org.jabref.logic.layout.format.ShortMonthFormatter;
 import org.jabref.logic.layout.format.ToLowerCase;
 import org.jabref.logic.layout.format.ToUpperCase;
@@ -565,6 +567,10 @@ private LayoutFormatter getLayoutFormatterByName(String name) {
                     new ReplaceWithEscapedDoubleQuotes();
             case "HayagrivaType" ->
                     new HayagrivaType();
+            case "NumberMonth" ->
+                new NumberMonthFormatter();
+            case "SafeFileName" ->
+                new SafeFileName();
             default ->
                     null;
         };

jablib/src/main/java/org/jabref/logic/layout/format/NumberMonthFormatter.java

@@ -0,0 +1,18 @@
+package org.jabref.logic.layout.format;
+
+import java.util.Optional;
+
+import org.jabref.logic.layout.LayoutFormatter;
+import org.jabref.model.entry.Month;
+
+/**
+ * Convert the month name into the corresponding number and return 01 by default
+ */
+public class NumberMonthFormatter implements LayoutFormatter {
+
+    @Override
+    public String format(String fieldText) {
+        Optional<Month> month = Month.parse(fieldText);
+        return month.map(Month::getTwoDigitNumber).orElse("01");
+    }
+}

jablib/src/main/java/org/jabref/logic/layout/format/SafeFileName.java

@@ -0,0 +1,14 @@
+package org.jabref.logic.layout.format;
+
+import org.jabref.logic.layout.LayoutFormatter;
+
+/**
+ * Remove all the characters that are not allowed by the OS in file names
+ */
+public class SafeFileName implements LayoutFormatter {
+
+    @Override
+    public String format(String fieldText) {
+        return fieldText.replaceAll("[\\\\/:*?\"<>|]", "");
+    }
+}

jablib/src/main/resources/l10n/JabRef_en.properties

@@ -472,6 +472,7 @@ The\ marked\ area\ does\ not\ contain\ any\ legible\ text!=The marked area does
 HTML\ table=HTML table
 HTML\ table\ (with\ Abstract\ &\ BibTeX)=HTML table (with Abstract & BibTeX)
 Markdown\ titles=Markdown titles
+Markdown\ academicpages=Academic Pages Markdowns
 
 Icon=Icon
 

jablib/src/main/resources/resource/layout/academicpages/academicpages.layout

@@ -0,0 +1,14 @@
+---
+title: "\format[RemoveLatexCommands,HTMLChars]{\title}"
+collection: publications
+category: \format{\entrytype}
+permalink: /publication/\format[RemoveLatexCommands,HTMLChars,Replace(\s,-),SafeFileName]{\title}
+excerpt: '\begin{note}\format[RemoveLatexCommands,HTMLChars]{\note}\end{note}'
+date: \format{\year}-\begin{month}\format[NumberMonth]{\month}\end{month}\begin{!month}01\end{!month}-\begin{day}\format{\day}\end{day}\begin{!day}01\end{!day}
+venue: '\format[RemoveLatexCommands,HTMLChars]{\journal}\begin{!journal}Unknown\end{!journal}'
+slidesurl: '\begin{file}\format[FileLink(pdf)]{\file}\end{file}\begin{!file}https://[insert username].github.io/files/[insert filename].pdf\end{!file}'
+paperurl: '\begin{file}\format[FileLink(pdf)]{\file}\end{file}\begin{!file}https://[insert username].github.io/files/[insert filename].pdf\end{!file}'
+bibtexurl: 'https://[insert username].github.io/files/[insert filename].bib'
+citation: '\format[HTMLChars]{\author}. (\format{\year}). "&quot;\format[RemoveLatexCommands,HTMLChars]{\title}.&quot; <i>\format[RemoveLatexCommands,HTMLChars]{\journal}</i>.'
+---
+\begin{abstract}\format{\abstract}\end{abstract}

jablib/src/test/java/org/jabref/logic/exporter/AcademicPagesExporterTest.java

@@ -0,0 +1,136 @@
+package org.jabref.logic.exporter;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.List;
+
+import org.jabref.logic.layout.LayoutFormatterPreferences;
+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.jabref.model.metadata.SelfContainedSaveOrder;
+
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.Answers;
+
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.Mockito.mock;
+
+class AcademicPagesExporterTest {
+
+    private AcademicPagesExporter exporter;
+    private BibDatabaseContext databaseContext;
+
+    @BeforeEach
+    void setUp() {
+        exporter = new AcademicPagesExporter(
+                mock(LayoutFormatterPreferences.class, Answers.RETURNS_DEEP_STUBS),
+                new SelfContainedSaveOrder(SaveOrder.OrderType.SPECIFIED, List.of()));
+        databaseContext = new BibDatabaseContext();
+    }
+
+    @Test
+    void exportArticleWithFullDateAndRequiredFieldsGeneratesCorrectFileNameAndContent(@TempDir Path tempDir) throws Exception {
+        BibEntry entry = new BibEntry(StandardEntryType.Article)
+                .withCitationKey("testKey")
+                .withField(StandardField.TITLE, "Test Title")
+                .withField(StandardField.AUTHOR, "Test Author")
+                .withField(StandardField.YEAR, "2023")
+                .withField(StandardField.MONTH, "05")
+                .withField(StandardField.DAY, "12")
+                .withField(StandardField.JOURNAL, "Test Journal");
+
+        exporter.export(databaseContext, tempDir, List.of(entry));
+
+        // Verify file name follows pattern: YYYY-MM-DD-title.md
+        Path expectedFile = tempDir.resolve("2023-05-12-test-title.md");
+        assertTrue(Files.exists(expectedFile));
+
+        String content = Files.readString(expectedFile);
+
+        // Verify YAML front matter fields
+        assertTrue(content.contains("title: \"Test Title\""));
+        assertTrue(content.contains("date: 2023-05-12"));
+        assertTrue(content.contains("venue: 'Test Journal'"));
+        assertTrue(content.contains("citation: 'Test Author (2023). \"Test Title.\" <i>Test Journal</i>.'"));
+    }
+
+    @Test
+    void exportArticleWithMissingMonthAndDayDefaultsToJanuaryFirst(@TempDir Path tempDir) throws Exception {
+        BibEntry entry = new BibEntry(StandardEntryType.Article)
+                .withCitationKey("testKey")
+                .withField(StandardField.TITLE, "No Date")
+                .withField(StandardField.YEAR, "2023");
+
+        exporter.export(databaseContext, tempDir, List.of(entry));
+
+        // Expect default date 2023-01-01
+        Path expectedFile = tempDir.resolve("2023-01-01-no-date.md");
+        assertTrue(Files.exists(expectedFile));
+
+        String content = Files.readString(expectedFile);
+        assertTrue(content.contains("date: 2023-01-01"));
+    }
+
+    @Test
+    void exportArticleWithAbstractAppendsAbstractAfterYamlFrontMatter(@TempDir Path tempDir) throws Exception {
+        BibEntry entry = new BibEntry(StandardEntryType.Article)
+                .withCitationKey("testKey")
+                .withField(StandardField.TITLE, "Abstract Paper")
+                .withField(StandardField.YEAR, "2023")
+                .withField(StandardField.ABSTRACT, "This is a test abstract.");
+
+        exporter.export(databaseContext, tempDir, List.of(entry));
+
+        Path expectedFile = tempDir.resolve("2023-01-01-abstract-paper.md");
+        assertTrue(Files.exists(expectedFile));
+
+        String content = Files.readString(expectedFile);
+
+        // Abstract should be outside the YAML block (after the second '---')
+        assertTrue(content.contains("---"));
+        assertTrue(content.endsWith("\nThis is a test abstract.\n"));
+    }
+
+    @Test
+    void exportMultipleEntriesGeneratesMultipleIndividualMarkdownFiles(@TempDir Path tempDir) throws Exception {
+        BibEntry entry1 = new BibEntry(StandardEntryType.Article)
+                .withCitationKey("key1")
+                .withField(StandardField.TITLE, "Paper One")
+                .withField(StandardField.YEAR, "2023");
+
+        BibEntry entry2 = new BibEntry(StandardEntryType.Book)
+                .withCitationKey("key2")
+                .withField(StandardField.TITLE, "Book Two")
+                .withField(StandardField.YEAR, "2022");
+
+        exporter.export(databaseContext, tempDir, List.of(entry1, entry2));
+
+        // Verify both files exist
+        assertTrue(Files.exists(tempDir.resolve("2023-01-01-paper-one.md")));
+        assertTrue(Files.exists(tempDir.resolve("2022-01-01-book-two.md")));
+    }
+
+    @Test
+    void exportInProceedingsWithBooktitleUsesBooktitleAsVenueAlias(@TempDir Path tempDir) throws Exception {
+        BibEntry entry = new BibEntry(StandardEntryType.InProceedings)
+                .withCitationKey("testKey")
+                .withField(StandardField.TITLE, "Conference Paper")
+                .withField(StandardField.YEAR, "2023")
+                .withField(StandardField.BOOKTITLE, "Conference Proceedings");
+
+        exporter.export(databaseContext, tempDir, List.of(entry));
+
+        Path expectedFile = tempDir.resolve("2023-01-01-conference-paper.md");
+        assertTrue(Files.exists(expectedFile));
+
+        String content = Files.readString(expectedFile);
+
+        // 'venue' should be populated from 'booktitle' since 'journal' is missing
+        assertTrue(content.contains("venue: 'Conference Proceedings'"));
+    }
+}