[**δΈζ**](./README.zh.md)
# [Academic File Converter](https://github.com/GetRD/academic-file-converter)
[](https://pypi.python.org/pypi/academic)
[](https://discord.com/channels/722225264733716590/742892432458252370/742895548159492138)
[](https://github.com/sponsors/gcushen)
[](https://twitter.com/GeorgeCushen)
[](https://github.com/gcushen)
### π Easily import publications and Jupyter notebooks to your Markdown-formatted website or book
**Features**
* **Import Jupyter notebooks** as blog posts or book chapters
* **Import publications** (such as **books, conference proceedings, and journals**) from your reference manager to your Markdown-formatted website or book
* Simply export a BibTeX file from your reference manager, such as [Zotero](https://www.zotero.org), and provide this as the input to the converter tool
* **Compatible with all static website generators** such as Next, Astro, Gatsby, Hugo, etc.
* **Easy to use** - 100% Python, no dependency on complex software such as Pandoc
* **Automate** file conversions using a [GitHub Action](https://github.com/HugoBlox/hugo-blox-builder/blob/main/starters/blog/.github/workflows/import-notebooks.yml)
**Community**
- π [View the **documentation** below](#installation)
- π¬ [Chat live with the **community** on Discord](https://discord.gg/z8wNYzb)
- π¦ Twitter: [@GetResearchDev](https://twitter.com/GetResearchDev) [@GeorgeCushen](https://twitter.com/GeorgeCushen) [#MadeWithAcademic](https://twitter.com/search?q=%23MadeWithAcademic&src=typed_query)
## β€οΈ Support Open Research & Open Source
We are on a mission to foster **open research** by developing **open source** tools like this.
To help us develop this open source software sustainably under the MIT license, we ask all individuals and businesses that use it to help support its ongoing maintenance and development via sponsorship and contributing.
Support the open research movement:
- βοΈ [**Star** this project on GitHub](https://github.com/GetRD/academic-file-converter)
- β€οΈ [Become a **GitHub Sponsor** and **unlock perks**](https://github.com/sponsors/gcushen)
- βοΈ [**Donate a coffee**](https://github.com/sponsors/gcushen?frequency=one-time)
- π©βπ» [**Contribute**](#contribute)
## Installation
Open your **Terminal** or **Command Prompt** app and enter one of the installation commands below.
### With Pipx
For the **easiest** installation, install with [Pipx](https://pypa.github.io/pipx/):
pipx install academic
Pipx will **automatically install the required Python version for you** in a dedicated environment.
### With Pip
To install using the Python's Pip tool, ensure you have [Python 3.11+](https://realpython.com/installing-python/) installed and then run:
pip3 install -U academic
## Usage
Open your Command Line or Terminal app and use the `cd` command to navigate to the folder containing the files you wish to convert, for example:
cd ~/Documents/my_website
### Import publications
Download references from your reference manager, such as Zotero, in the Bibtex format.
Say we downloaded our publications to a file named `my_publications.bib` within the website folder, let's import them into the `content/publication/` folder:
academic import my_publications.bib content/publication/ --compact
Optional arguments:
* `--compact` Generate minimal markdown without comments or empty keys
* `--overwrite` Overwrite any existing publications in the output folder
* `--normalize` Normalize tags by converting them to lowercase and capitalizing the first letter (e.g. "sciEnCE" -> "Science")
* `--featured` Flag these publications as *featured* (to appear in your website's *Featured Publications* section)
* `--verbose` or `-v` Show verbose messages
* `--help` Help
### Import full text and cover image
After importing publications, we suggest you:
- Edit the Markdown body of each publication to add the full text directly to the page (if the publication is open access), or otherwise, to add supplementary notes for each publication
- Add an image named `featured` to each publication's folder to visually represent your publication on the page and for sharing on social media
- Add the publication PDF to each publication folder (for open access publications), to enable your website visitors to download your publication
[Learn more in the Hugo Blox Docs](https://docs.hugoblox.com/reference/content-types/).
### Import blog posts from Jupyter Notebooks
Say we have our notebooks in a `notebooks` folder within the website folder, let's import them into the `content/post/` folder:
academic import 'notebooks/*.ipynb' content/post/ --verbose
Optional arguments:
* `--overwrite` Overwrite any existing blog posts in the output folder
* `--verbose` or `-v` Show verbose messages
* `--help` Help
## Contribute
Interested in contributing to **open source** and **open research**?
Learn [how to contribute code on Github](https://codeburst.io/a-step-by-step-guide-to-making-your-first-github-contribution-5302260a2940).
Check out the [open issues](https://github.com/GetRD/academic-file-converter/issues) and contribute a [Pull Request](https://github.com/GetRD/academic-file-converter/pulls).
For local development, clone this repository and use Poetry to install and run the converter using the following commands:
git clone https://github.com/GetRD/academic-file-converter.git
cd academic-file-converter
poetry install
poetry run academic import tests/data/article.bib output/publication/ --overwrite --compact
poetry run academic import 'tests/data/**/*.ipynb' output/post/ --overwrite --verbose
When preparing a contribution, run the following checks and ensure that they all pass:
- Lint: `make lint`
- Format: `make format`
- Test: `make test`
- Type check: `make type`
### Help beta test the dev version
You can help test the latest development version by installing the latest `main` branch from GitHub:
pip3 install -U git+https://github.com/GetRD/academic-file-converter.git
## License
Copyright 2018-present [George Cushen](https://georgecushen.com).
Licensed under the [MIT License](https://github.com/GetRD/academic-file-converter/blob/main/LICENSE.md).
[](https://github.com/GetRD/academic-file-converter/blob/main/LICENSE.md)
Raw data
{
"_id": null,
"home_page": "https://hugoblox.com/",
"name": "academic",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11.5",
"maintainer_email": "",
"keywords": "research,Jupyter,bibtex,markdown,latex,publication,reference,academic,converter",
"author": "George Cushen",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/cf/a2/c2f2b33fa096c65cba1f99bfd55336a11cf328ea8d8fa913a230b5b44754/academic-0.11.2.tar.gz",
"platform": null,
"description": "[**\u4e2d\u6587**](./README.zh.md)\n\n# [Academic File Converter](https://github.com/GetRD/academic-file-converter)\n\n[](https://pypi.python.org/pypi/academic)\n[](https://discord.com/channels/722225264733716590/742892432458252370/742895548159492138)\n[](https://github.com/sponsors/gcushen)\n[](https://twitter.com/GeorgeCushen)\n[](https://github.com/gcushen) \n\n\n### \ud83d\udcda Easily import publications and Jupyter notebooks to your Markdown-formatted website or book\n\n\n\n**Features**\n\n* **Import Jupyter notebooks** as blog posts or book chapters\n* **Import publications** (such as **books, conference proceedings, and journals**) from your reference manager to your Markdown-formatted website or book\n * Simply export a BibTeX file from your reference manager, such as [Zotero](https://www.zotero.org), and provide this as the input to the converter tool\n* **Compatible with all static website generators** such as Next, Astro, Gatsby, Hugo, etc.\n* **Easy to use** - 100% Python, no dependency on complex software such as Pandoc\n* **Automate** file conversions using a [GitHub Action](https://github.com/HugoBlox/hugo-blox-builder/blob/main/starters/blog/.github/workflows/import-notebooks.yml)\n\n**Community**\n\n- \ud83d\udcda [View the **documentation** below](#installation)\n- \ud83d\udcac [Chat live with the **community** on Discord](https://discord.gg/z8wNYzb)\n- \ud83d\udc26 Twitter: [@GetResearchDev](https://twitter.com/GetResearchDev) [@GeorgeCushen](https://twitter.com/GeorgeCushen) [#MadeWithAcademic](https://twitter.com/search?q=%23MadeWithAcademic&src=typed_query)\n\n## \u2764\ufe0f Support Open Research & Open Source\n\nWe are on a mission to foster **open research** by developing **open source** tools like this.\n\nTo help us develop this open source software sustainably under the MIT license, we ask all individuals and businesses that use it to help support its ongoing maintenance and development via sponsorship and contributing.\n\nSupport the open research movement:\n\n - \u2b50\ufe0f [**Star** this project on GitHub](https://github.com/GetRD/academic-file-converter)\n - \u2764\ufe0f [Become a **GitHub Sponsor** and **unlock perks**](https://github.com/sponsors/gcushen)\n - \u2615\ufe0f [**Donate a coffee**](https://github.com/sponsors/gcushen?frequency=one-time)\n - \ud83d\udc69\u200d\ud83d\udcbb [**Contribute**](#contribute)\n\n## Installation\n\nOpen your **Terminal** or **Command Prompt** app and enter one of the installation commands below.\n\n### With Pipx\n\nFor the **easiest** installation, install with [Pipx](https://pypa.github.io/pipx/): \n\n pipx install academic\n\nPipx will **automatically install the required Python version for you** in a dedicated environment.\n\n### With Pip\n\n To install using the Python's Pip tool, ensure you have [Python 3.11+](https://realpython.com/installing-python/) installed and then run:\n\n pip3 install -U academic\n\n## Usage\n\nOpen your Command Line or Terminal app and use the `cd` command to navigate to the folder containing the files you wish to convert, for example:\n\n cd ~/Documents/my_website\n\n### Import publications\n\nDownload references from your reference manager, such as Zotero, in the Bibtex format.\n\nSay we downloaded our publications to a file named `my_publications.bib` within the website folder, let's import them into the `content/publication/` folder:\n\n academic import my_publications.bib content/publication/ --compact\n\nOptional arguments:\n\n* `--compact` Generate minimal markdown without comments or empty keys\n* `--overwrite` Overwrite any existing publications in the output folder\n* `--normalize` Normalize tags by converting them to lowercase and capitalizing the first letter (e.g. \"sciEnCE\" -> \"Science\")\n* `--featured` Flag these publications as *featured* (to appear in your website's *Featured Publications* section)\n* `--verbose` or `-v` Show verbose messages\n* `--help` Help\n\n### Import full text and cover image\n\nAfter importing publications, we suggest you:\n- Edit the Markdown body of each publication to add the full text directly to the page (if the publication is open access), or otherwise, to add supplementary notes for each publication\n- Add an image named `featured` to each publication's folder to visually represent your publication on the page and for sharing on social media\n- Add the publication PDF to each publication folder (for open access publications), to enable your website visitors to download your publication\n \n[Learn more in the Hugo Blox Docs](https://docs.hugoblox.com/reference/content-types/).\n\n### Import blog posts from Jupyter Notebooks\n\nSay we have our notebooks in a `notebooks` folder within the website folder, let's import them into the `content/post/` folder:\n\n academic import 'notebooks/*.ipynb' content/post/ --verbose\n\nOptional arguments:\n\n* `--overwrite` Overwrite any existing blog posts in the output folder\n* `--verbose` or `-v` Show verbose messages\n* `--help` Help\n\n## Contribute\n\nInterested in contributing to **open source** and **open research**?\n\nLearn [how to contribute code on Github](https://codeburst.io/a-step-by-step-guide-to-making-your-first-github-contribution-5302260a2940).\n\nCheck out the [open issues](https://github.com/GetRD/academic-file-converter/issues) and contribute a [Pull Request](https://github.com/GetRD/academic-file-converter/pulls). \n\nFor local development, clone this repository and use Poetry to install and run the converter using the following commands:\n\n git clone https://github.com/GetRD/academic-file-converter.git\n cd academic-file-converter\n poetry install\n poetry run academic import tests/data/article.bib output/publication/ --overwrite --compact\n poetry run academic import 'tests/data/**/*.ipynb' output/post/ --overwrite --verbose\n\nWhen preparing a contribution, run the following checks and ensure that they all pass:\n\n- Lint: `make lint`\n- Format: `make format`\n- Test: `make test`\n- Type check: `make type`\n\n### Help beta test the dev version\n\nYou can help test the latest development version by installing the latest `main` branch from GitHub:\n\n pip3 install -U git+https://github.com/GetRD/academic-file-converter.git\n\n## License\n\nCopyright 2018-present [George Cushen](https://georgecushen.com).\n\nLicensed under the [MIT License](https://github.com/GetRD/academic-file-converter/blob/main/LICENSE.md).\n\n\n[](https://github.com/GetRD/academic-file-converter/blob/main/LICENSE.md)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Import Bibtex publications and Jupyter Notebook blog posts into your Markdown-formatted website or book.",
"version": "0.11.2",
"project_urls": {
"Documentation": "https://docs.hugoblox.com/reference/content-types/",
"Homepage": "https://hugoblox.com/",
"Repository": "https://github.com/GetRD/academic-file-converter"
},
"split_keywords": [
"research",
"jupyter",
"bibtex",
"markdown",
"latex",
"publication",
"reference",
"academic",
"converter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6c085e1b48688d4bebec3eeda3971ad4d9ee1d165ceefa22c68a6571812a2103",
"md5": "315c04ab32ec798a0d96f32a06fe289a",
"sha256": "28e459cf8fe261d870f8663f33fb8d90263cece7967d70c5db55ebbde07d59ba"
},
"downloads": -1,
"filename": "academic-0.11.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "315c04ab32ec798a0d96f32a06fe289a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11.5",
"size": 15305,
"upload_time": "2023-11-26T21:23:42",
"upload_time_iso_8601": "2023-11-26T21:23:42.148854Z",
"url": "https://files.pythonhosted.org/packages/6c/08/5e1b48688d4bebec3eeda3971ad4d9ee1d165ceefa22c68a6571812a2103/academic-0.11.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cfa2c2f2b33fa096c65cba1f99bfd55336a11cf328ea8d8fa913a230b5b44754",
"md5": "2cd78973e38f0b26638a021faccbf93b",
"sha256": "16c2a3a774018b5af64f445f17c6d4851f1c9a9b0cac8e32fd9dbc74c81253c5"
},
"downloads": -1,
"filename": "academic-0.11.2.tar.gz",
"has_sig": false,
"md5_digest": "2cd78973e38f0b26638a021faccbf93b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11.5",
"size": 15471,
"upload_time": "2023-11-26T21:23:43",
"upload_time_iso_8601": "2023-11-26T21:23:43.338411Z",
"url": "https://files.pythonhosted.org/packages/cf/a2/c2f2b33fa096c65cba1f99bfd55336a11cf328ea8d8fa913a230b5b44754/academic-0.11.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-26 21:23:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GetRD",
"github_project": "academic-file-converter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "academic"
}
JSON
