Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jimniels/readlists
A readlist is a mixtape, but for online content.
https://github.com/jimniels/readlists
Last synced: 22 days ago
JSON representation
A readlist is a mixtape, but for online content.
- Host: GitHub
- URL: https://github.com/jimniels/readlists
- Owner: jimniels
- Created: 2020-04-27T18:12:10.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-10-15T06:02:37.000Z (about 1 year ago)
- Last Synced: 2024-08-02T16:52:18.934Z (3 months ago)
- Language: JavaScript
- Homepage: https://readlists.jim-nielsen.com
- Size: 3.42 MB
- Stars: 55
- Watchers: 2
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- my-awesome-github-stars - jimniels/readlists - A readlist is a mixtape, but for online content. (JavaScript)
README
# Readlists
Bringing back the spirit of the original Readlists service. [Check out the blog post for more deets](https://blog.jim-nielsen.com/2021/reintroducing-readlists/).
## How it works
[readlists.jim-nielsen.com](https://readlists.jim-nielsen.com) is merely a GUI for creating and editing a “Readlist”.
What’s a Readlist? At its core, a Readlist is simply a [JSON feed](https://www.jsonfeed.org/) with content from [mercury-parser](https://github.com/postlight/mercury-parser).
An example Readlist:
```json
{
"version": "https://jsonfeed.org/version/1.1",
"title": "My Readlist",
"description": "A custom description of the Readlist",
"items": [
{
"id": "https://en.wikipedia.org/wiki/Thunder_(mascot)",
"url": "https://en.wikipedia.org/wiki/Thunder_(mascot)",
"title": "Thunder (mascot)",
"content_html": "...
Thunder is the stage name for the..."
}
]
}
```
You can use [the web GUI](https://readlists.jim-nielsen.com) to create a Readlist
### Saving a Readlist
Readlists are saved locally in your browser (using `localStorage`). You can save the data of a Readlist to a JSON file, host it at a URL, and then allow others to import it themselves. It falls to you to save and distribute (the URLs for) your Readlists. Yeah it’s more work for you, but hey, on the flip side the data is all yours. Do whatever you want with it.
### Generate a Readlist From a List of Links
You can programatically generate a Readlist by doing a GET to `/api/create?urls=` along with a comma separated list of links, e.g.
`https://readlists.jim-nielsen.com/api/create?urls=https://example.com/articles/1,https://example.com/articles/2`
For example, here’s a Readlist link with three random articles:
https://readlists.jim-nielsen.com/api/create?urls=https://piperhaywood.com/family-recipe-for-classic-white-frosting/,https://rachsmith.com/is-typescript-good/,https://daverupert.com/2023/08/vibe-check-28/
And here’s that same Readlist as a curl (`-L` follows the redirect):
```
curl -L "https://readlists.jim-nielsen.com/api/create?urls=\
https://piperhaywood.com/family-recipe-for-classic-white-frosting/,\
https://rachsmith.com/is-typescript-good/,\
https://daverupert.com/2023/08/vibe-check-28/"
```
Easily create a list of your favorite articles and share it with a friend via a single link!
### Import an exisiting Readlist
When you create and customize your Readlist, you can share it with others by allowing them to import it into the UI.
To do so, host your Readlist file (a JSON feed) somewhere on the web and append `/?import=` to the URL, e.g.
`/?import=https://example.com/path/to/readlist.json`
Or, you can generate a Readlist on the fly and open it in the GUI editor using the instructions above on generating links:
https://readlists.jim-nielsen.com/?import=https://readlists.jim-nielsen.com/api/create?urls=https://piperhaywood.com/family-recipe-for-classic-white-frosting/,https://rachsmith.com/is-typescript-good/,https://daverupert.com/2023/08/vibe-check-28/
## Local Development
- Local dev `npm start` (you'll need `netlify-cli` installed globally)
- Prod build `npm run build`
## ToDos
- [ ] Maybe get to these someday
- [ ] Use Zod for types
- [ ] Error boundary that clears localStorage
- [ ] Setup shared proptypes
- [ ] write more tests for stuff in utils
- [ ] abstract shared CSS for different pages
- [ ] edit HTML on client
- [ ] Double check epub export with the old readlist epubs
- [ ] handling multiple error toasts in successions
- [ ] Validation of readlists
- [ ] Transitions
- [ ] Address the @TODO items in code
- [ ] Refactor handlers to be at bottom of hooks?
- [ ] Draggable sorting?
- [ ] support proxing requests, so CORS wouldn't have to be supported to pull in a remote readlist