{"id":22741335,"url":"https://github.com/paulofeh/reader-to-capacities","last_synced_at":"2025-04-12T21:11:23.249Z","repository":{"id":265605032,"uuid":"896325467","full_name":"paulofeh/reader-to-capacities","owner":"paulofeh","description":"A Python script that syncs archived articles from Readwise Reader to Capacities, including highlights and notes. This tool helps maintain your PKM system by automatically creating weblink objects in Capacities from curated Readwise Reader content. Synchronization runs through GitHub Actions with secure credential handling and processes.","archived":false,"fork":false,"pushed_at":"2025-04-09T03:27:17.000Z","size":203,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-09T04:25:18.322Z","etag":null,"topics":["api-integration","automation","capacities","github-actions","knowledge-management","pkm","productivity","python","readwise","readwise-reader"],"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/paulofeh.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":"2024-11-30T04:04:45.000Z","updated_at":"2025-04-09T03:27:20.000Z","dependencies_parsed_at":"2024-11-30T05:18:46.603Z","dependency_job_id":"4e2788a2-5fd2-46a7-983d-d0a7ef121ac5","html_url":"https://github.com/paulofeh/reader-to-capacities","commit_stats":null,"previous_names":["paulofeh/reader-to-capacities"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulofeh%2Freader-to-capacities","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulofeh%2Freader-to-capacities/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulofeh%2Freader-to-capacities/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paulofeh%2Freader-to-capacities/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paulofeh","download_url":"https://codeload.github.com/paulofeh/reader-to-capacities/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631676,"owners_count":21136562,"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":["api-integration","automation","capacities","github-actions","knowledge-management","pkm","productivity","python","readwise","readwise-reader"],"created_at":"2024-12-11T00:09:48.742Z","updated_at":"2025-04-12T21:11:23.222Z","avatar_url":"https://github.com/paulofeh.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Readwise Reader to Capacities Sync\n\nThis project automates the synchronization of archived articles from Readwise Reader to Capacities, helping maintain a well-organized Personal Knowledge Management (PKM) system. The script fetches articles you've archived in Readwise Reader, including their highlights and notes, and creates corresponding weblinks in your Capacities workspace.\n\n## Key Features\n\nThe synchronization process includes:\n- Fetches only archived articles from Readwise Reader, ensuring intentional content curation\n- Transfers article metadata including title, description, and author\n- Preserves all highlights and notes made in Readwise Reader\n- Maintains a history of processed articles to prevent duplicates\n- Processes articles in configurable batches to manage API usage\n- Runs manually through GitHub Actions with secure credential handling\n\n## Prerequisites\n\nBefore setting up this project, you'll need:\n- A Readwise Reader account with API access\n- A Capacities account with API access\n- A GitHub account for hosting the workflow\n- Python 3.10 or higher for local development\n\n## Setup Instructions\n\n### Local Development Setup\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/yourusername/reader-to-capacities.git\ncd reader-to-capacities\n```\n\n2. Create and activate a virtual environment:\n```bash\npython -m venv venv\n# On Windows\nvenv\\Scripts\\activate\n# On macOS/Linux\nsource venv/bin/activate\n```\n\n3. Install dependencies:\n```bash\npip install -r requirements.txt\n```\n\n4. Create a `.env` file in the project root with your API credentials:\n```plaintext\nREADWISE_TOKEN=your_readwise_token\nCAPACITIES_TOKEN=your_capacities_token\nCAPACITIES_SPACE_ID=your_space_id\n```\n\n### GitHub Setup\n\n1. Create a new repository on GitHub\n\n2. Add the following secrets in your repository settings (Settings \u003e Secrets and variables \u003e Actions):\n- `READWISE_TOKEN`: Your Readwise API token\n- `CAPACITIES_TOKEN`: Your Capacities API token\n- `CAPACITIES_SPACE_ID`: Your Capacities space ID\n\n3. Push your code to GitHub:\n```bash\ngit remote add origin https://github.com/yourusername/reader-to-capacities.git\ngit branch -M main\ngit push -u origin main\n```\n\n## Configuration\n\nThe script's behavior can be customized through the `config.py` file:\n\n- `ARTICLES_PER_RUN`: Number of articles to process in each execution (default: 5)\n- `ARTICLES_UPDATED_AFTER`: Starting date for fetching updated articles (format: \"YYYY-MM-DD\")\n\n## Usage\n\n### Local Execution\n\nTo run the script locally:\n```bash\npython main.py\n```\n\n### GitHub Actions\n\nTo run the sync through GitHub Actions:\n1. Go to your repository on GitHub\n2. Click the \"Actions\" tab\n3. Select \"Sync Readwise Articles to Capacities\"\n4. Click \"Run workflow\"\n5. Select the branch (usually 'main')\n6. Click \"Run workflow\"\n\n## How It Works\n\n1. The script fetches archived articles from Readwise Reader that were updated after the specified date\n2. For each article:\n   - Retrieves associated highlights and notes\n   - Creates a weblink in Capacities with:\n     - Original article title and URL\n     - Author information\n     - Description/summary\n     - Highlights formatted in markdown\n     - Any additional notes\n3. Maintains a list of processed articles to prevent duplicates\n4. Updates the processing history in the repository\n\n## Project Structure\n\n```plaintext\nreader-to-capacities/\n├── .github/\n│   └── workflows/\n│       └── sync_articles.yml    # GitHub Actions workflow\n├── .gitignore                   # Git ignore configuration\n├── config.py                    # Configuration settings\n├── main.py                      # Main script\n├── capacities_client.py         # Capacities API client\n├── requirements.txt             # Python dependencies\n├── processed_ids.txt            # Processing history\n└── README.md                    # Project documentation\n```\n\n## Error Handling\n\nThe script includes robust error handling for common scenarios:\n- API rate limiting\n- Network connectivity issues\n- Invalid article formats\n- Missing highlights or metadata\n\n## Contributing\n\nFeel free to submit issues and enhancement requests. All contributions are welcome!\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\nThis project was built using:\n- [Readwise Reader API](https://readwise.io/api_deets)\n- [Capacities API](https://api.capacities.io)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulofeh%2Freader-to-capacities","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaulofeh%2Freader-to-capacities","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaulofeh%2Freader-to-capacities/lists"}