Academic File Converter is a free, open-source Python command-line tool that imports BibTeX publications and Jupyter notebooks into Markdown files for any static site generator.
What is Academic File Converter?
Academic File Converter runs on the command line and takes two kinds of input: BibTeX files exported from reference managers such as Zotero, and Jupyter notebook files (.ipynb). It converts them into Markdown files structured for the content/publication/ and content/post/ folders of a static site. The converter is written in 100% Python and has no dependency on Pandoc. It was created by George Cushen, the founder of Hugo Blox (Wowchemy), and is maintained under the GetRD organization. The project is licensed under the MIT License.
Key Features
- BibTeX import — Reads publication records exported as BibTeX from reference managers like Zotero, covering books, conference proceedings, and journal articles, and writes them as individual Markdown files with front matter.
- Jupyter notebook import — Converts .ipynb notebooks into Markdown blog posts or book chapters, preserving code, output, and markdown cells.
- Static site generator compatibility — Generates output that works with Next.js, Astro, Gatsby, Hugo, Jekyll, and other static site generators that consume Markdown.
- Pure Python implementation — Runs with just Python 3.11+ and pip; no dependency on Pandoc or other document-conversion software.
- CLI options — Supports flags like
--compactto strip comments and empty keys,--overwriteto replace existing files,--normalizeto standardize tags,--featuredto mark publications as featured, and--verbosefor logging. - GitHub Action automation — Ships a GitHub Action workflow for Hugo Blox that automatically imports notebooks and publications on repository events.
Who is it for?
- Academic researchers who maintain a publication list on a personal Hugo Blox or other static site; they can export a BibTeX library from Zotero and run a single command to generate all publication pages.
- Data scientists and notebook authors who want to turn Jupyter notebooks into readable blog posts without manually copying content into Markdown.
- Static site developers who want to automate content ingestion from reference managers and notebooks as part of a CI/CD pipeline using the provided GitHub Action.
What can you do with Academic File Converter?
- Researchers: Convert a BibTeX file like
my_publications.bibinto Markdown pages incontent/publication/withacademic import my_publications.bib content/publication/ --compact. - Data scientists: Turn all notebooks in a
notebooks/folder into blog posts incontent/post/usingacademic import 'notebooks/*.ipynb' content/post/ --verbose. - Site maintainers: Automate the import process with the Hugo Blox GitHub Action so new publications and notebooks are converted whenever the repository updates.
How does Academic File Converter work?
First install with pipx install academic or pip3 install -U academic (Python 3.11+ required). Then cd into your website folder and run the academic import command pointing at either a .bib file or a notebook path, specifying the output directory. The tool parses the input, extracts metadata and content, and writes Markdown files. For publications, the generated files include front matter and a body you can edit to add full text, a featured image, and a PDF for download.
Pricing
Free and open source under the MIT License. The project asks individuals and businesses that use it to support ongoing development via GitHub Sponsorship or one-time donations.
Alternatives
- Pandoc — a general-purpose document converter that can handle BibTeX but requires a more complex setup.
- Jupyter nbconvert — converts notebooks to Markdown and other formats but does not import BibTeX publications.
FAQ
Is Academic File Converter free?
Yes. The tool is free and open source under the MIT License. You can install it from PyPI with pip or pipx and use it without any licensing fees. The project does request optional sponsorship to support its maintenance.
What input formats does Academic File Converter support?
It supports BibTeX files exported from reference managers such as Zotero, and Jupyter notebook files (.ipynb). BibTeX input covers books, conference proceedings, and journal articles. Output is always Markdown.
Does Academic File Converter work with Hugo?
Yes, it works with Hugo and every other static site generator that consumes Markdown, including Next.js, Astro, Gatsby, and Jekyll. There is also a GitHub Action provided for Hugo Blox to automate imports.
Do I need Pandoc to use it?
No. Academic File Converter is implemented entirely in Python and has no dependency on Pandoc or other document-conversion software. You only need Python 3.11 or newer and the academic package.
