{"id":13658131,"url":"https://github.com/thomashirtz/notion-scholar","last_synced_at":"2025-04-04T18:05:56.323Z","repository":{"id":38363201,"uuid":"428311592","full_name":"thomashirtz/notion-scholar","owner":"thomashirtz","description":"Reference management solution using Python and Notion.","archived":false,"fork":false,"pushed_at":"2024-10-17T16:29:40.000Z","size":1503,"stargazers_count":163,"open_issues_count":1,"forks_count":26,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-28T17:11:09.209Z","etag":null,"topics":["bibliography","notion","notion-api","notion-database","notion-py","publications","reference-manager","research-paper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thomashirtz.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2021-11-15T15:09:37.000Z","updated_at":"2025-03-27T05:54:26.000Z","dependencies_parsed_at":"2023-10-16T23:18:38.342Z","dependency_job_id":"78e7d3a0-2361-406b-8a28-0a6565985d36","html_url":"https://github.com/thomashirtz/notion-scholar","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fnotion-scholar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fnotion-scholar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fnotion-scholar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomashirtz%2Fnotion-scholar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thomashirtz","download_url":"https://codeload.github.com/thomashirtz/notion-scholar/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226213,"owners_count":20904465,"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":["bibliography","notion","notion-api","notion-database","notion-py","publications","reference-manager","research-paper"],"created_at":"2024-08-02T05:00:56.638Z","updated_at":"2025-04-04T18:05:56.301Z","avatar_url":"https://github.com/thomashirtz.png","language":"Python","funding_links":["https://www.paypal.com/donate/?hosted_button_id=2KQR9V6PRSBPC"],"categories":["Python"],"sub_categories":[],"readme":"# notion-scholar\n\nReference management solution using Python and Notion.\n\nThe main idea of this app is to allow to furnish a Notion database using a BibTex formatted string or file. It also helps you to organize papers, create a bibliography and give you the opportunity to annotate the publications directly on their Notion's pages.\n\n\n![publication-database](resources/notion-scholar-database.png)\n\n_Example of a database obtained using notion-scholar._\n\n## Installation\n\n\n```\npip install git+https://github.com/thomashirtz/notion-scholar#egg=notion-scholar\n```\nYou can now call the application using `notion-scholar` or `ns`\n\n\u003cdetails\u003e\u003csummary\u003eNever used python nor github before ?\u003c/summary\u003e\n\n1. Install Python 3.7 or above (tutorial available online)\n2. Install [pip](https://pip.pypa.io/en/stable/installation/) (Generally included with Python)\n3. Run the command `pip install ...` above using your machine command line (Maybe need to launch the command prompt as administrator on Windows)\n\n\u003c/details\u003e\n\n## Setting up\n\n### 1. Creation of a notion database\n\nYou can either duplicate the page template using the link below, or create a new database with the properties listed in requirements.\n\n**Template**\n\n\u003cdetails\u003e\u003csummary\u003ePreview images\u003c/summary\u003e\n\n![dashboard](resources/notion-scholar-dashboard.png)\n____\n![category-page](resources/notion-scholar-category-page.png)\n\n\u003c/details\u003e\n\n[Link to the template](https://thomashirtz.notion.site/Bibliography-408958535d9140ec9ee557eb044bb97a)\n\n**Requirements**\n\nThe properties necessary to import publications in a database are the following:\n\n| Property Name      | Property Type |\n| ------------------ | ------------- |\n| Title              | Title         |\n| Authors            | Text          |\n| Year               | Number        |\n| Journal            | Text          |\n| Filename           | Text          |\n| URL                | URL           |\n| Abstract           | Text          |\n| DOI                | Text          |\n| Type               | Select        |\n| Bibtex             | Text          |\n| Inbox              | Checkbox      |\n\n**No space should be in the names of the properties.**\n\n### 2. Creation of an integration\n\nCreate an [integration](https://www.notion.so/my-integrations) for the notion-scholar database. The integration needs to target the workplace containing the publication database.\n\nOption needed:\n- [x] Internal Integration\n- [x] Read content\n- [x] Update content\n- [x] Insert content\n\nCopy the `Internal Integration Token` for the [step 4](#4-set-the-token-and-database_id-in-notion-scholar).\n\n### 3. Share the database with the Integration\n\nGo to your database in notion =\u003e Click on `...` (top right) =\u003e `+ Add connections` =\u003e Select the integration that you just created.\n\nCopy the link of the database (simply the URL on a browser, on the application =\u003e Click on `...` =\u003e `Copy Link`) for the [step 4](#4-set-the-token-and-database_id-in-notion-scholar).\n\nIt is the *database page* and not the dashboard page that needs to be integrated. Moreover, it is also the URL of the database page that needs to be set into `notion-scholar`.  \n\n### 4. Set the token and database_id in notion-scholar\nFor the first use, it is recommended to set up the configuration file. The main parameters to save are the token (which will be securely saved using the [keyring](https://pypi.org/project/keyring/) library) and the database-url.\n```\nns set-config --token \u003ctoken\u003e --database-id \u003cdatabase_id\u003e\n```\nor\n```\nns set-config -t \u003ctoken\u003e -db \u003cdatabase_id\u003e\n```\n\nThe database_id is one part of the URL:\n`https://www.notion.so/\u003cworkspace_name\u003e/\u003cdatabase_id\u003e?v=\u003cview_id\u003e`\n\nFor example, if the database url is :  \n`https://www.notion.so/thomashirtz/be31bb3f190f46c69e804785cc83c7ce?v=5674957e71e24aeb91d6db65f7978f0c`   \nThe command that needs to be used to set the database is :   \n`ns set-config -db be31bb3f190f46c69e804785cc83c7ce`  \n\n\n### 5. Set the bib file path (not required, but recommended)\nIf you want to set the default bib path that will be used when the `ns` run is called, you can set it by typing:\n```\nns set-config --bib-file-path \u003cbib_file_path\u003e\n```\nor\n```\nns set-config -f \u003cbib_file_path\u003e\n```\n**The bib file needs to exist and the file path needs to be absolute.**\n\n## How to use ?\n\nThere is three main way to use this application:\n\n1. [Setting up](#5-set-the-bib-file-path-not-required-but-recommended) the `bib-file-path` and call the `run` mode (It will automatically upload the new publications from the bib file into the database):\n```\nns run\n```\n2. Giving the `bib-file-path` argument:\n```\nns run -f \u003cbib-file-path\u003e\n```\n3. Giving a `bib-string` argument (/!\\ be careful to type three quotes `\"\"\"` before pasting the `bib-string`) :\n\n```\nns run -s \"\"\"\u003cbib-string\u003e\"\"\"\n```\n**The `--token` (`-t`) and the `--database_url` (`-db`) are also required, however, if they have been `set`, they don't need to be added again to the argument list.**\n\n## Help\n\nFor getting help it is possible to call:\n```\nns --help\n```\n\n```\nusage: Use \"notion-scholar --help\" or \"ns --help\" for more information\n\nnotion-scholar\n\npositional arguments:\n  {run,download,clear-config,inspect-config,set-config}\n                        Selection of the action\n    run                 Run notion-scholar.\n    download            Download the bibtex entries present in the database.\n    clear-config        Clear the notion-scholar config.\n    inspect-config      Inspect the notion-scholar config.\n    set-config          Save the default values of notion-scholar.\n\noptional arguments:\n  -h, --help            show this help message and exit\n```\n\nFive main modes exist: `run`, `download`, `set-config`, ` inspect-config` and `clear-config`. The help can be called this way:\n```\nns \u003cmode\u003e --help\n```\n\n\u003cdetails\u003e\u003csummary\u003eExample:\u003c/summary\u003e\n\n\n```\nns run --help\n```\n\n```\nusage: Use \"notion-scholar --help\" or \"ns --help\" for more information run [-h] [-t] [-db] [-f] [-s]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -t , --token          Token used to connect to Notion. (default: None)\n  -db , --database-id   Database that will be furnished. The database_id can be found in the url of the database:\n                        https://www.notion.so/{workspace_name}/{database_id}?v={view_id} (default: None)\n  -f , --bib-file-path\n                        Bib file that will be used. This argument is required if the bib file is not saved in the\n                        config and no bib-string is passed. (default: None)\n  -s , --bib-string     Bibtex entries to add (must be in-between three quotes \"\"\"\u003cbib-string\u003e\"\"\"). By default, the\n                        entries will be saved to the bib file from the config. It is possible to disable this behavior\n                        by changing the \"save\" option: \"ns setup -save false\".\n```\n\n```\nns set-config --help\n```\n\n```\nusage: Use \"notion-scholar --help\" or \"ns --help\" for more information set [-h] [-f] [-s] [-t] [-db]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -f , --bib-file-path\n                        Save the input file path in the user config using \"platformdirs\". The path must be absolute\n                        and the file need to exist. (current: None)\n  -s , --save           Set whether the entries from \"bib-string\" will be saved in the bib file. (current: True)\n  -t , --token          Save the Notion token using \"keyring\". (current: None)\n  -db , --database-id   Save the database-id in the user config using the library \"platformdirs\". The database_id can\n                        be found in the url of the database:\n                        https://www.notion.so/{workspace_name}/{database_id}?v={view_id} (current: None)```\n```\n\u003c/details\u003e\n\n\n## Tips\n### Bibtex keys\n\nWhen uploading a BibTex file into the database, the BibTex citekey will be mapped to the property \"filename\". This is because it seems convenient to have the same name for the key and the filename. **It is therefore advised to change the citekey before uploading to Notion.** (If you want to change it manually afterwards you would need to change both the `Bibtex` and the `Filename` property, which is not very convinient.)\n\nThis is ~ the nomenclature I used for the citekey [(source)](https://academia.stackexchange.com/a/139742). Feel free to take inspiration:\n\n\u003cdetails\u003e\u003csummary\u003eNomenclature\u003c/summary\u003e\n\n**Filename:**\n`aaaayyyyxxxx.pdf`\n\n**Where:**\n- `aaaa`: Name of the first author (variable length)\n- `yyyy`: Year of publication (fixed length)\n- `xxxx`: First word of title, minus articles and other small words (variable length)\n\n**For example:**\nAttention Is All You Need, Ashish Vaswani et al., 2017\n\n**Would give:**\n`vaswani2017attention.pdf`\n\nIf an author publish two papers the same year with the same beginning first word, it is possible to add an `1` and `2` depending on which one was the first released.\n\nFor example:\n- Soft Actor-Critic Algorithms and Applications, Tuomas Haarnoja et al., 2018\n  `haarnoja2018soft1.pdf`\n- Soft Actor-Critic: Off-Policy Maximum Entropy Deep Reinforcement Learning with a Stochastic Actor, Tuomas Haarnoja et al., 2018\n  `haarnoja2018soft2.pdf`\n\n\u003c/details\u003e\n\n### Copy equation properties\n\nIt is possible to copy the equation in the table view. [Here](https://www.reddit.com/r/Notion/comments/erdtad/comment/ff4zefs/?utm_source=share\u0026utm_medium=web2x\u0026context=3) is a comment to explain how, it can be very useful.\n\n\n## Feedbacks\n\nIf you want to see a new feature, or you have some feedback to give, feel free to email me at [thomashirtz@pm.me](mailto:thomashirtz@pm.me).\n\n## Buy me a coffee ツ\n\nIf this repository helped you or you if you like this project, feel free to support me!  \n\n\u003ca href=\"https://www.paypal.com/donate/?hosted_button_id=2KQR9V6PRSBPC\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/stefan-niedermann/paypal-donate-button/master/paypal-donate-button.png\" alt=\"Donate with PayPal\" width=\"180\" /\u003e\n\u003c/a\u003e\n\n## License\n\n     Copyright 2021 Thomas Hirtz\n\n     Licensed under the Apache License, Version 2.0 (the \"License\");\n     you may not use this file except in compliance with the License.\n     You may obtain a copy of the License at\n\n         http://www.apache.org/licenses/LICENSE-2.0\n\n     Unless required by applicable law or agreed to in writing, software\n     distributed under the License is distributed on an \"AS IS\" BASIS,\n     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n     See the License for the specific language governing permissions and\n     limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomashirtz%2Fnotion-scholar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomashirtz%2Fnotion-scholar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomashirtz%2Fnotion-scholar/lists"}