{"id":13725196,"url":"https://github.com/GjjvdBurg/paper2remarkable","last_synced_at":"2025-05-07T19:33:15.348Z","repository":{"id":45017669,"uuid":"168977039","full_name":"GjjvdBurg/paper2remarkable","owner":"GjjvdBurg","description":"Fetch an academic paper or web article and send it to the reMarkable tablet with a single command","archived":false,"fork":false,"pushed_at":"2024-10-14T22:25:06.000Z","size":1769,"stargazers_count":337,"open_issues_count":11,"forks_count":27,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-06T16:02:55.465Z","etag":null,"topics":["arxiv","remarkable","remarkable-tablet"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GjjvdBurg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-02-03T18:15:07.000Z","updated_at":"2024-11-06T06:52:24.000Z","dependencies_parsed_at":"2023-02-10T06:30:53.982Z","dependency_job_id":"6f642df3-7687-4727-9816-d0b232d426ad","html_url":"https://github.com/GjjvdBurg/paper2remarkable","commit_stats":{"total_commits":447,"total_committers":9,"mean_commits":"49.666666666666664","dds":0.03579418344519014,"last_synced_commit":"780eee6ef024149e8001c5ddac3627dc3d39fc3a"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GjjvdBurg%2Fpaper2remarkable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GjjvdBurg%2Fpaper2remarkable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GjjvdBurg%2Fpaper2remarkable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GjjvdBurg%2Fpaper2remarkable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GjjvdBurg","download_url":"https://codeload.github.com/GjjvdBurg/paper2remarkable/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224468003,"owners_count":17316289,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arxiv","remarkable","remarkable-tablet"],"created_at":"2024-08-03T01:02:15.518Z","updated_at":"2024-11-14T15:30:54.353Z","avatar_url":"https://github.com/GjjvdBurg.png","language":"Python","funding_links":["https://www.buymeacoffee.com/GjjvdBurg"],"categories":["Python","remarkable-tablet","Other"],"sub_categories":["Template Builders"],"readme":"# paper2remarkable\n\n[![PyPI version](https://badge.fury.io/py/paper2remarkable.svg)](https://pypi.org/project/paper2remarkable)\n[![Build status](https://github.com/GjjvdBurg/paper2remarkable/workflows/build/badge.svg)](https://github.com/GjjvdBurg/paper2remarkable/actions)\n[![Downloads](https://pepy.tech/badge/paper2remarkable)](https://pepy.tech/project/paper2remarkable)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/GjjvdBurg/paper2remarkable/master/.github/illustration.png\" height=\"300\"\u003e\n\u003c/p\u003e\n\n``paper2remarkable`` is a command line program for quickly and easily \ntransferring an academic paper to your [reMarkable](https://remarkable.com/):\n\n```\n$ p2r https://arxiv.org/abs/1811.11242\n```\n\nThere is also support for transferring an article from a website:\n\n```\n$ p2r https://hbr.org/2019/11/getting-your-team-to-do-more-than-meet-deadlines\n```\n\nThe script can be run through the ``p2r`` command line program or via Docker\n(see below). If you're using MacOS, you might be interested in the [Alfred\nworkflow](#alfred-workflow) or [Printing to p2r](#printing). On Linux, a \nbackground terminal such as [Guake](http://guake-project.org/) can be very \nhandy. Note that even without a reMarkable, this program can make downloading \npapers easier (just use the `-n` flag).\n\n## Introduction\n\n``paper2remarkable`` makes it as easy as possible to get a PDF on your \nreMarkable from any of the following sources:\n\n* [arXiv](https://arxiv.org/)\n* [ACL Web](https://www.aclweb.org/anthology/)\n* [ACM Digital Library](https://dl.acm.org/dl.cfm)\n* [CVF](https://openaccess.thecvf.com/menu)\n* [DiVA](https://diva-portal.org/)\n* [ECCC](https://eccc.weizmann.ac.il/reports/menu/)\n* [IACR](https://eprint.iacr.org/)\n* [JMLR](http://jmlr.org)\n* [Nature](https://www.nature.com)\n* [NBER](https://www.nber.org)\n* [NeurIPS](https://papers.nips.cc/)\n* [OpenReview](https://openreview.net/)\n* [PMLR](http://proceedings.mlr.press/)\n* [PubMed Central](https://www.ncbi.nlm.nih.gov/pmc/)\n* [SemanticScholar](https://www.semanticscholar.org/)\n* [SpringerLink](https://link.springer.com/)\n* A generic URL to a PDF file\n* A local PDF or Postscript file\n* Any article on a website\n\nThe program aims to be flexible to the exact source URL, so for many of the \nacademic sources you can either provide a URL to the abstract page or to the \nPDF file. If you have a source that you would like to see added to the list, \nlet me know!\n\n``paper2remarkable`` takes the source URL and:\n\n1. Downloads the pdf\n2. Removes the arXiv timestamp (for arXiv sources)\n3. Crops the pdf to remove unnecessary borders\n4. Shrinks the pdf file to reduce the filesize\n5. Generates a nice filename based on author/title/year of the paper\n6. Uploads it to your reMarkable using \n   [rMapi](https://github.com/ddvk/rmapi).\n\nOptionally, you can:\n\n- Download a paper but not upload to the reMarkable using the ``-n`` switch.\n- Insert a blank page after each page using the ``-b`` switch (useful for note \n  taking!)\n- Center (``-c``) or right-align (``-r``) the pdf on the reMarkable (default \n  is left-aligned), or disable cropping altogether (``-k``).\n- Provide an explicit filename using the ``--filename`` parameter\n- Specify the location on the reMarkable to place the file (default ``/``)\n\nHere's an example with verbose mode enabled that shows everything the script \ndoes by default:\n\n```\n$ p2r -v https://arxiv.org/abs/1811.11242\n2019-05-30 00:38:27 - INFO - Starting ArxivProvider\n2019-05-30 00:38:27 - INFO - Getting paper info from arXiv\n2019-05-30 00:38:27 - INFO - Downloading url: https://arxiv.org/abs/1811.11242\n2019-05-30 00:38:27 - INFO - Generating output filename\n2019-05-30 00:38:27 - INFO - Created filename: Burg_Nazabal_Sutton_-_Wrangling_Messy_CSV_Files_by_Detecting_Row_and_Type_Patterns_2018.pdf\n2019-05-30 00:38:27 - INFO - Downloading file at url: https://arxiv.org/pdf/1811.11242.pdf\n2019-05-30 00:38:32 - INFO - Downloading url: https://arxiv.org/pdf/1811.11242.pdf\n2019-05-30 00:38:32 - INFO - Removing arXiv timestamp\n2019-05-30 00:38:34 - INFO - Cropping pdf file\n2019-05-30 00:38:37 - INFO - Shrinking pdf file\n2019-05-30 00:38:38 - INFO - Starting upload to reMarkable\n2019-05-30 00:38:42 - INFO - Upload successful.\n```\n\n## Installation\n\n*For ArchLinux, paper2remarkable can be installed through the [Arch User \nRepository](https://aur.archlinux.org/packages/paper2remarkable/).*\n\nThe script requires the following external programs to be available:\n\n- [pdftk](https://www.pdflabs.com/tools/pdftk-the-pdf-toolkit/), \n  [qpdf](http://qpdf.sourceforge.net/), or \n  [pdftk-java](https://gitlab.com/pdftk-java/pdftk), whichever your package \n  manager provides.\n- [GhostScript](https://www.ghostscript.com/)\n- [rMAPI](https://github.com/ddvk/rmapi)\n\nSpecifically:\n\n1. First install [rMAPI](https://github.com/ddvk/rmapi), using the \n   instructions available here: https://github.com/ddvk/rmapi#install\n\n2. Then install system dependencies:\n   - **Arch Linux:** ``pacman -S pdftk ghostscript poppler``\n   - **Ubuntu:** ``apt-get install pdftk ghostscript poppler-utils``. Replace \n     ``pdftk`` with ``qpdf`` if your distribution doesn't package ``pdftk``.\n   - **MacOS:** ``brew install pdftk-java ghostscript poppler`` (using [HomeBrew](https://brew.sh/)).\n   - **Windows:** Installers or executables are available for \n     [qpdf](https://github.com/qpdf/qpdf/releases) (for instance the mingw \n     binary executables) and \n     [GhostScript](https://www.ghostscript.com/download/gsdnld.html). \n     Importantly, Windows support is untested and these are generic \n     instructions, so we welcome clarifications where needed. The Docker \n     instructions below may be more convenient on Windows.\n\n3. Finally, install ``paper2remarkable``:\n   ```bash\n   $ pip install paper2remarkable\n   ```\n   this installs the ``p2r`` command line program.\n\n\u003e [!IMPORTANT]\n\u003e On certain newer Debian and Ubuntu-based distributions, running \n\u003e\n\u003e ```bash\n\u003e $ pip install paper2remarkable\n\u003e ```\n\u003e\n\u003e will raise an ```error: externally-managed-environment```.\n\u003e Rather, run \n\u003e\n\u003e ```bash\n\u003e $ pipx install paper2remarkable\n\u003e ```\n\u003e\n\u003e to install the  ``p2r`` command line program.\n\n**Optionally**, you can install:\n\n- [pdftoppm](https://linux.die.net/man/1/pdftoppm) (recommended for speed). \n  Usually part of a [Poppler](https://poppler.freedesktop.org/) installation.\n\n- the [ReadabiliPy](https://github.com/alan-turing-institute/ReadabiliPy) \n  package with Node.js support, to allow using \n  [Readability.js](https://github.com/mozilla/readability) for HTML articles. \n  This is known to improve the output of certain web articles.\n\nIf any of the dependencies (such as rmapi or ghostscript) are not available on \nthe ``PATH`` variable, you can supply them with the relevant options to the \nscript (for instance ``p2r --rmapi /path/to/rmapi``). If you run into trouble \nwith the installation, please let me know by opening an issue [on \nGithub][github-url].\n\n## Usage\n\nThe full help of the script is as follows. Hopefully the various command line \nflags are self-explanatory, but if you'd like more information see the [man \npage](docs/man.md) (``man p2r``) or open an issue [on GitHub][github-url].\n\n```\nusage: p2r [-h] [-b] [-c] [-d] [-e] [-n] [-p REMARKABLE_DIR] [-r] [-k] [-v]\n           [-V] [-f FILENAME] [--gs GS] [--pdftoppm PDFTOPPM] [--pdftk PDFTK]\n           [--qpdf QPDF] [--rmapi RMAPI] [--css CSS] [--font-urls FONT_URLS]\n           [-C CONFIG] input [input ...]\n\nPaper2reMarkable version 0.9.4\n\npositional arguments:\n  input                 One or more URLs to a paper or paths to local PDF\n                        files\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -b, --blank           Add a blank page after every page of the PDF\n  -c, --center          Center the PDF on the page, instead of left align\n  -d, --debug           debug mode, doesn't upload to reMarkable\n  -e, --experimental    enable experimental features\n  -n, --no-upload       don't upload to reMarkable, save the output in current\n                        directory\n  -p REMARKABLE_DIR, --remarkable-path REMARKABLE_DIR\n                        directory on reMarkable to put the file (created if\n                        missing, default: /)\n  -r, --right           Right align so the menu doesn't cover it\n  -k, --no-crop         Don't crop the pdf file\n  -v, --verbose         be verbose\n  -V, --version         Show version and exit\n  -f FILENAME, --filename FILENAME\n                        Filename to use for the file on reMarkable\n  --gs GS               path to gs executable (default: gs)\n  --pdftoppm PDFTOPPM   path to pdftoppm executable (default: pdftoppm)\n  --pdftk PDFTK         path to pdftk executable (default: pdftk)\n  --qpdf QPDF           path to qpdf executable (default: qpdf)\n  --rmapi RMAPI         path to rmapi executable (default: rmapi)\n  --css CSS             path to custom CSS file for HTML output\n  --font-urls FONT_URLS\n                        path to custom font urls file for HTML output\n  -C CONFIG, --config CONFIG\n                        path to config file (default: ~/.paper2remarkable.yml)\n```\n\nBy default ``paper2remarkable`` makes a PDF fit better on the reMarkable by \nchanging the page size and removing unnecessary whitespace. Some tools for \nexporting a PDF with annotations do not handle different page sizes properly, \ncausing annotations to be misplaced (see \n[discussion](https://github.com/GjjvdBurg/paper2remarkable/issues/77)). If \nthis is an issue for you, you can disable cropping using the \n``-k``/``--no-crop`` option to ``p2r``.\n\nFor HTML sources (i.e. web articles) you can specify custom styling using the \n``--css`` and ``--font-urls`` options. The default style in the [HTML \nprovider](https://github.com/GjjvdBurg/paper2remarkable/blob/a6e50d07748c842f1f0a09e4b173c87850c6ddee/paper2remarkable/providers/html.py#L36) \ncan serve as a starting point.\n\nLocal PDF or Postscript files can be supplied too, using ``p2r /path/to/file.pdf``.\n\nA configuration file can be used to provide commonly-used command line \noptions. By default the configuration file at ``~/.paper2remarkable.yml`` is \nused if it exists, but an alternative location can be provided with the \n``-C/--config`` flag. Command line flags override the settings in the \nconfiguration file.  See the [config.example.yml](./config.example.yml) file \nfor an example configuration file and an overview of supported options.\n\n## Alfred Workflow\n\nOn MacOS, you can optionally install [this Alfred workflow][workflow]. Alfred \nis [a launcher for MacOS](https://www.alfredapp.com/).\n\nOnce installed, you can then use `rm` command and `rmb` (for the `--blank` \npages to insert blank pages between pages for notes) with a URL passed. The \nglobal shortcut `Alt-P` will send the current selection to `p2r`. Note that by \ndefault `--right` is passed and `p2r` is executed in your `bash` environment. \nYou can edit the Workflow in Alfred if this doesn't work for your setup.\n\n![Alfred Screenshot](https://raw.githubusercontent.com/GjjvdBurg/paper2remarkable/master/.github/alfred.png)\n\n[workflow]: https://github.com/GjjvdBurg/paper2remarkable/blob/master/Remarkable.alfredworkflow?raw=true \n\n## Printing\n\nPrinting to `p2r` allows printing prompts to save directly to your reMarkable\ntablet, passing through `p2r` for processing.\n\nFor MacOS, you can follow [the guide][print-guide] for printing with `rmapi`,\nbut for the bash script, instead use this script:\n\n```\nfor f in \"$@\"\ndo\n\tbash -c -l \"p2r --right '$f'\" \ndone\n```\n\n[print-guide]: https://github.com/ddvk/rmapi/blob/master/docs/tutorial-print-macosx.md\n\n## Docker\n\nIf you'd like to avoid installing the dependencies directly on your machine, \nyou can use the Dockerfile. To make this work you will need ``git`` and \n``docker`` installed.\n\nFirst clone this repository with `git clone` and `cd` inside of it, then build \nthe container:\n\n```bash\ndocker build -t p2r .\n```\n\n### Authorization\n\n``paper2remarkable`` uses [rMapi](https://github.com/ddvk/rmapi) to sync \ndocuments to the reMarkable. The first time you run ``paper2remarkable`` you \nwill have to authenticate rMapi using a one-time code provided by reMarkable. \nBy default, rMapi uses the ``${HOME}/.rmapi`` file as a configuration file to \nstore the credentials, and so this is the location we will use in the commands \nbelow. If you'd like to use a different location for the configuration (for \ninstance, ``${HOME}/.config/rmapi/rmapi.conf``), make sure to change the \ncommands below accordingly.\n\nIf you already have a `~/.rmapi` file with the authentication details, you can \nskip this section. Otherwise we'll create it and run ``rmapi`` in the docker \ncontainer for authentication:\n\n```bash\n$ touch ${HOME}/.rmapi\n$ docker run --rm -i -t -v \"${HOME}/.rmapi:/home/user/.rmapi:rw\" --entrypoint=rmapi p2r version\n```\n\nThis command will print a link where you can obtain a one-time code to \nauthenticate rMapi and afterwards print the rMapi version (the version number \nmay be different):\n\n```bash\nReMarkable Cloud API Shell\nrmapi version: 0.0.12\n```\n\n### Usage\n\nUse the container by replacing `p2r` with `docker run --rm -v \n\"${HOME}/.rmapi:/home/user/.rmapi:rw\" p2r`, e.g.\n\n```\n# print help and exit\ndocker run --rm -v \"${HOME}/.rmapi:/home/user/.rmapi:rw\" p2r --help\n\n# equivalent to above usage\ndocker run --rm -v \"${HOME}/.rmapi:/home/user/.rmapi:rw\" p2r -v https://arxiv.org/abs/1811.11242\n\n# to transfer a local file in the current directory\ndocker run --rm -v \"${HOME}/.rmapi:/home/user/.rmapi:rw\" -v \"$(pwd):/home/user:ro\" p2r -v localfile.pdf\n```\n\nFor transferring local files using the Docker image, you may find [this helper \nfunction](https://github.com/GjjvdBurg/paper2remarkable/issues/34#issuecomment-610852258) \nuseful.\n\nYou can also create an [alias](http://tldp.org/LDP/abs/html/aliases.html) in \nyour ``~/.bashrc`` file to abstract away the Docker commands:\n\n```bash\n# in ~/.bashrc\n\nalias p2r=\"docker run --rm -v \\\"${HOME}/.rmapi:/home/user/.rmapi:rw\\\" p2r\"\n```\n\nAfter running ``source ~/.bashrc`` to activate the alias, you can then use \n``paper2remarkable`` through Docker by calling ``p2r`` from the command line.\n\n# Notes\n\nLicense: MIT\n\nIf you find a problem or want to suggest a feature, please open an issue [on \nGithub][github-url]. You're helping to make this project better for everyone! \n\nThanks to all the \n[contributors](https://github.com/GjjvdBurg/paper2remarkable/graphs/contributors) \nwho've helped to support the project.\n\n[![BuyMeACoffee](https://img.shields.io/badge/%E2%98%95-buymeacoffee-ffdd00)](https://www.buymeacoffee.com/GjjvdBurg)\n\n[github-url]: https://github.com/GjjvdBurg/paper2remarkable\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGjjvdBurg%2Fpaper2remarkable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGjjvdBurg%2Fpaper2remarkable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGjjvdBurg%2Fpaper2remarkable/lists"}