{"id":13566067,"url":"https://github.com/plandes/zotsite","last_synced_at":"2025-05-15T11:07:24.368Z","repository":{"id":49157464,"uuid":"127065145","full_name":"plandes/zotsite","owner":"plandes","description":"Export Zotero to a stand-alone web site","archived":false,"fork":false,"pushed_at":"2025-01-11T20:07:21.000Z","size":9834,"stargazers_count":345,"open_issues_count":4,"forks_count":36,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-14T18:14:26.327Z","etag":null,"topics":["academia","papers","research","website-generation","zotero"],"latest_commit_sha":null,"homepage":"https://plandes.github.io/zotsite/","language":"JavaScript","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/plandes.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","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":"2018-03-28T01:17:00.000Z","updated_at":"2025-04-05T12:15:57.000Z","dependencies_parsed_at":"2023-02-12T19:15:42.033Z","dependency_job_id":"f0dde069-8f5a-4aef-b09f-3ae92b4b7b45","html_url":"https://github.com/plandes/zotsite","commit_stats":{"total_commits":197,"total_committers":5,"mean_commits":39.4,"dds":"0.030456852791878153","last_synced_commit":"74922564b358e9cf3bd65bdc198abe2d44b07eef"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fzotsite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fzotsite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fzotsite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/plandes%2Fzotsite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/plandes","download_url":"https://codeload.github.com/plandes/zotsite/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248933340,"owners_count":21185460,"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":["academia","papers","research","website-generation","zotero"],"created_at":"2024-08-01T13:02:01.378Z","updated_at":"2025-04-14T18:14:31.445Z","avatar_url":"https://github.com/plandes.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","research"],"sub_categories":[],"readme":"# Zotsite: A Zotero Export Utility\n\n[![PyPI][pypi-badge]][pypi-link]\n[![Python 3.11][python311-badge]][python311-link]\n[![Build Status][build-badge]][build-link]\n\nThis project exports your local [Zotero] library to a usable HTML website with\nfollowing features:\n\n* Easily access your papers, site snapshots, notes from a navigation tree.\n* Provides metadata from collections and attachments (i.e. referenes etc).\n* Display PDF papers and website snapshot (the latter as framed).\n* Search function dynamically narrows down the papers you're looking for.\n* Embed links to a specific collection, article, item, note etc.\n* Export only a portion of your collection with regular expressions using the\n  collection name.\n* [BetterBibtex] integration.\n* Snazzy look and feel from the latest [Bootstrap] CSS/Javascript library.\n\n\u003c!-- markdown-toc start - Don't edit this section. Run M-x markdown-toc-refresh-toc --\u003e\n## Table of Contents\n\n- [Documentation](#documentation)\n- [Obtaining](#obtaining)\n- [Process](#process)\n- [Sample Site Demonstration](#sample-site-demonstration)\n- [Requirements](#requirements)\n- [Usage](#usage)\n    - [Command Line](#command-line)\n    - [API](#api)\n    - [Configuration File](#configuration-file)\n- [Screenshot](#screenshot)\n- [Ubuntu and Linux Systems with Python 3.5 or Previous Version](#ubuntu-and-linux-systems-with-python-35-or-previous-version)\n- [Attribution](#attribution)\n- [Todo](#todo)\n- [Zotero Plugin Listing](#zotero-plugin-listing)\n- [Changelog](#changelog)\n- [Community](#community)\n- [License](#license)\n\n\u003c!-- markdown-toc end --\u003e\n\n\n## Documentation\n\nSee the [full documentation](https://plandes.github.io/zotsite/index.html).\nThe [API reference](https://plandes.github.io/zotsite/api.html) is also\navailable.\n\n\n## Obtaining\n\nThe library can be installed with pip from the [pypi] repository:\n```bash\npip3 install zensols.zotsite\n```\n\n\n## Process\n\nThe tool does the following:\n\n1. Exports the meta data (directory structure, references, notes, etc) from\n   your [Zotero] library.  On MacOS, this is done by querying the file system\n   SQLite DB files.\n2. Copies a static site that enables traversal of the exported data.\n3. Copies your [Zotero] stored papers, snapshot (sites) etc.\n4. Generates a navigation tree to easily find your papers/content.\n\n\n## Sample Site Demonstration\n\nSee the [live demo], which provides a variety of resources found in my own\nlibrary.  *Note:* To my knowledge, all of these resources are free to\ndistribute and violate no laws.  If I've missed one,\nplease [create an issue](CONTRIBUTING.md).\n\n## Requirements\n\n[BetterBibtex] plugin for Zotero.\n\n\n## Usage\n\nThe library is typically used from the command line to create websites, but it\ncan also be used as an API from Python.\n\n\n### Command Line\n\nThe command line program has two modes: show configuration (a good first step)\nand to create the web site.  You can see what the program is parsing from your\n[Zotero] library:\n\n```bash\nzotsite print\n```\n\nTo create the stand-alone site, run the program (without the angle brackets):\n\n```bash\nzotsite export\n```\n\nIf your library is not in the default `~/zotero` directory you will need to\nchange that path by making a zotsite.conf config file.  This will create the\nhtml files in the directory `./zotsite`:\n\n```bash\nzotsite export --collection zotsite.conf\n```\n\nA mapping of BetterBibtex citation keys to Zotero's database unique *item keys*\ncan be useful to scripts:\n```bash\nzotsite citekey -k all\n```\n\nThe tool also provides a means of finding where papers are by *item key*:\n```bash\nzotsite docpath -k all\n```\n\nSee [usage](doc/usage.md) for more information.  Command line usage as provided\nwith the `--help` option.\n\n\n### API\n\nThe API provides access to a Python object that creates the website, can\nresolve BetterBibtex citation keys to Zotero unique identifier *item keys* and\nprovide paths of item attachments (such as papers).\n\nThe following example come from [this working script](example/showpaper.py).\n\n```python\n\u003e\u003e\u003e from typing import Dict, Any\n\u003e\u003e\u003e from pathlib import Path\n\u003e\u003e\u003e from zensols.zotsite import Resource, ApplicationFactory\n# get the resource facade objects, which provides access to create the site,\n# citation and path lookup methods\n\u003e\u003e\u003e resource: Resource = ApplicationFactory.get_resource()\n# get a mapping from \u003clibrary ID\u003e_\u003citem key\u003e to entry dictionaries\n\u003e\u003e\u003e entries: Dict[str, Dict[str, Any]] = resource.cite_db.entries\n# get a mapping from item key (sans library ID) to the attachment path\n\u003e\u003e\u003e paths: Dict[str, Path] = resource.zotero_db.item_paths\n# create BetterBibtex citation key to item key mapping\n\u003e\u003e\u003e bib2item: Dict[str, str] = dict(map(\n...     lambda e: (e['citationKey'], e['itemKey']),\n...     entries.values()))\n# get the item key from the citation key\n\u003e\u003e\u003e itemKey: str = bib2item['landesCALAMRComponentALignment2024']\n# get the path using the Zotero DB item key\n\u003e\u003e\u003e paper_path: Path = paths[itemKey]\n\u003e\u003e\u003e print(paper_path)\n# display the paper (needs 'pip install zensols.rend')\n\u003e\u003e\u003e from zensols.rend import ApplicationFactory as RendAppFactory\n\u003e\u003e\u003e RendAppFactory.get_browser_manager()(paper_path)\n```\n\n\n### Configuration File\n\nEither an environment variable `ZOTSITERC` must be set or a `-c` configuration\noption must be given and point to a file to customize how the program works.\nSee the test [configuration file] for an example and inline comments for more\ndetail on how and what can be configured.\n\n\n## Screenshot\n\nAlso see the [live demo].\n\n![Screenshot][screenshot]\n\n\n## Ubuntu and Linux Systems with Python 3.5 or Previous Version\n\nPlease [read this issue](https://github.com/plandes/zotsite/issues/4) if you\nare installing a Ubuntu or any Linux system with Python 3.5 or previous\nversion.\n\n\n## Attribution\n\nThis software uses:\n* Python 3\n* [jQuery] version 3\n* [DataTables] version 1.12\n* [Bootstrap] version 4\n* [Tree View] for Bootstrap\n* [Popper] for tooltips\n* [Copy to Clipboard] function\n\n\n## Todo\n\n* Make the site portion a proper Javascript site.  Right now, all the `min`s\n  are added in the distribution to same directory as\n  the [main navigation/content](resources/site/src/js/zotero.js) file.\n* Use something like zotxt to make this work with a plugin rather than directly\n  against the SQLite DB.\n\n\n## Zotero Plugin Listing\n\nThis is listed as a [plugin] on the Zotero site.\n\n\n## Changelog\n\nAn extensive changelog is available [here](CHANGELOG.md).\n\n\n## Community\n\nPlease star this repository and let me know how and where you use this API.\nContributions as pull requests, feedback and any input is welcome.\n\n\n## License\n\n[MIT License](LICENSE.md)\n\nCopyright (c) 2019 - 2025 Paul Landes\n\n\n\u003c!-- links --\u003e\n[pypi]: https://pypi.org/project/zensols.zotsite/\n[pypi-link]: https://pypi.python.org/pypi/zensols.zotsite\n[pypi-badge]: https://img.shields.io/pypi/v/zensols.zotsite.svg\n[python311-badge]: https://img.shields.io/badge/python-3.11-blue.svg\n[python311-link]: https://www.python.org/downloads/release/python-3110\n[build-badge]: https://github.com/plandes/zotsite/workflows/CI/badge.svg\n[build-link]: https://github.com/plandes/zotsite/actions\n[gitter-link]: https://gitter.im/zoterosite/zotsite\n[gitter-badge]: https://badges.gitter.im/zoterosite/gitter.png\n\n[live demo]: https://plandes.github.io/zotsite/demo/index.html\n[screenshot]: https://raw.githubusercontent.com/plandes/zotsite/master/doc/snapshot.png\n\n[Zotero]: https://www.zotero.org\n[jQuery]: https://jquery.com\n[DataTables]: https://datatables.net\n[Bootstrap]: https://getbootstrap.com\n[Tree View]: https://github.com/jonmiles/bootstrap-treeview\n[Popper]: https://popper.js.org\n[plugin]: https://www.zotero.org/support/plugins#website_integration\n[Copy to Clipboard]: https://ourcodeworld.com/articles/read/143/how-to-copy-text-to-clipboard-with-javascript-easily\n[BetterBibtex]: https://github.com/retorquere/zotero-better-bibtex\n[configuration file]: test-resources/zotsite.conf\n[Python regular expression]: https://docs.python.org/3/library/re.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplandes%2Fzotsite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fplandes%2Fzotsite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fplandes%2Fzotsite/lists"}