Updated README

README.md

@@ -1,18 +1,69 @@
-# 🦉 Bubo Reader
+# 🦉 Bubo Reader (2.0)
 
 Bubo Reader is a hyper-minimalist <acronym title="Really Simple Syndication">RSS</acronym> and <acronym title="JavaScript Object Notation">JSON</acronym> feed reader you can deploy on your own server, [Netlify](https://netlify.com) in a few steps or [Glitch](https://glitch.com) in even fewer steps! The goal of the project is to generate a webpage that shows a list of links from a collection of feeds organized by category and website. That's it.
 
 It is named after this [silly robot owl](https://www.youtube.com/watch?v=MYSeCfo9-NI) from Clash of the Titans (1981).
 
-You can read more about how this project came about in my blog post '[Introducing Bubo RSS: An Absurdly Minimalist RSS Feed Reader](https://george.mand.is/2019/11/introducing-bubo-rss-an-absurdly-minimalist-rss-feed-reader/)'
+You can read more about how this project came about on my blog:  
+- [Introducing Bubo RSS: An Absurdly Minimalist RSS Feed Reader](https://george.mand.is/2019/11/introducing-bubo-rss-an-absurdly-minimalist-rss-feed-reader/).
 
+## Getting Started
+
+- Clone or fork the repo and run  `npm install` to install the dependencies.
+- Update `feeds.json` to include categories and links to feeds you would like to see.
+- Run `npm run build:bubo`
+
+That's it! You should now have a static page with links to the latest content from your feeds in the `public` folder, ready to serve.
+
+## Differences in Bubo 2.0
+
+Version 2.0 has introduced some substantial changes for Bubo! While the static output remains endearingly spartan, the engine that builds it has changed a bit.
+
+Hopefully all of these changes are in services of making this project more useful to others and encouraging outside contributions.
+
+Changes of note:
+
+- Bubo has been rewritten in [TypeScript](https://www.typescriptlang.org/). It's pretty slick! I anticipate the typing could be improved, but it's a start.
+- You fill find an `.nvmrc` file in the root of this project. Learn more [about nvm](https://github.com/nvm-sh/nvm) if you're unfamiliar.
+- The script will actually write your `index.html` file for you (Previously the build script simply ran `node src/index.js > output/index.html`). It makes a strong assumption that this file lives in the `public` folder.
+- There is a somewhat sophisticated mechansim in-place for batching & throttling your requests, if needed.
 ## Anatomy of Bubo Reader
 
-- `src/index.html` - a [Nunjucks](https://mozilla.github.io/nunjucks/) template that lets you change how the feeds are displayed
+The static pieces:
-- `output/style.css` - a CSS file to stylize your feed output
-- `src/feeds.json` - a JSON file containing the URLs for various site's feeds separated into categories
-- `src/index.js` - the script that loads the feeds and does the actual parsing and rendering
 
+- `conf/feeds.json` - a JSON file containing your feed URLS separated into categories.
+- `config/template.html` - a [Nunjucks](https://mozilla.github.io/nunjucks/) template that lets you change how the feeds are displayed. This can be changed to anything else you like— see below.
+- `public/style.css` - a CSS file to stylize your feed output.
+- `public/index.html` - The HTML file that gets automatically generated when Bubo is run.
+
+The engine:
+
+- `src/index.ts` - The primary script you run when you want to build a new version of Bubo. It will automatically fetch the latest content from your feeds and build a new static file at `public/index.html`.
+- `src/renderer.ts` — The renderer that loads Nunjucks, the template and understands how to process the incoming feed data. Prefer something else? This is the place to change it!
+- `src/utilities.ts` — A variety of parsing and normalization utilities for Bubo, hidden away to try and keep things clean.
+
+## Throttling
+
+In the main `index.ts` file you will find two values that allow yout to batch and throttle your feed requests:
+
+- `MAX_CONNECTIONS` dictates the maximium number of requests a batch can have going at once.
+- `DELAY_MS` dictates the amount of de;ay time between each batch.
+
+The default configuration is **no batching or throttling** beacuse `MAX_CONNECTIONS` is set to `Infinity`. If you wanted to change Bubo to only fetch one feed at a time every second you could set these values to:
+
+```javascript
+const MAX_CONNECTIONS = 1;
+const DELAY_MS = 1000;
+```
+
+If you wanted to limit things to 10 simultaneous requests every 2.5 seconds you could set it like so:
+
+```javascript
+const MAX_CONNECTIONS = 10;
+const DELAY_MS = 2500;
+```
+
+In practice, I've never _really_ run into an issue leaving `MAX_CONNECTIONS` set to `Infinity` but this feels like a sensible safeguard to design.
 ## Demos
 
 You can view live demos here:
@@ -34,19 +85,14 @@ Not the most exciting-looking demos, I'll admit, but they work!
 The quickest way is to remix the project on Glitch:
 [https://glitch.com/edit/#!/bubo-rss](https://glitch.com/edit/#!/bubo-rss)
 
-Just changed some feeds in `./src/feeds.json` file and you're set! If you'd like to modify the style or the template you can changed `./output/style.css` file or the `./src/template.html` file respectively.
+Just changed some feeds in `./config/feeds.json` file and you're set! If you'd like to modify the style or the template you can changed `./public/style.css` file or the `./config/template.html` file respectively.
-
-There is also a special `glitch` branch you can clone if you prefer:
-[https://github.com/georgemandis/bubo-rss/tree/glitch](https://github.com/georgemandis/bubo-rss/tree/glitch)
-
-The only difference between this branch and `master` is that it spins up a server using [Express](https://expressjs.com/) to serve your `./output/index.html` file on Glitch. Everything else is the same.
 
 <a id="netlify"></a>
 ## Deploying to Netlify
 
 - [Fork the repository](https://github.com/georgemandis/bubo-rss/fork)
-- From your forked repository go to and edit `src/feeds.json` to manage your feeds and categories
+- From your forked repository edit `config/feeds.json` to manage your feeds and categories
-- [Create a new site](https://app.netlify.com/start) on Netlify from GitHub 
+- [Create a new site](https://app.netlify.com/start) on Netlify from GitHub
 
 The deploy settings should automatically import from the `netlify.toml` file. All you'll need to do is confirm and you're ready to go!
 
@@ -61,21 +107,19 @@ To keep your feeds up to date you'll want to [setup a Build Hook](https://www.ne
 - [Zapier](https://zapier.com/)
 - [EasyCron](https://www.easycron.com/)
 
-If you already have a server running Linux and some command-line experience it might be simpler to setup a [cron job](https://en.wikipedia.org/wiki/Cron). 
-
 #### Using GitHub Actions
 
-This approach is a little different and requires some modifications to the repository. Netlify started billing for [build minutes](https://www.netlify.com/pricing/faq/) very shortly after I published this project. Running `npm build` and downloading all of the RSS feeds took up a substantial number of these, particularly if you had a process pinging the webhook and triggering a build every 15 minutes or so.
+Coming soon—there is an old branch that demonstrates this, but it needs to be revisisted in light of Bubo 2.0.
 
-How is the The GitHub Action-based approach different? The same build process runs, but this time it's on GitHub's servers via the Action. It then **commits** the newly created file generated at `./output/index.html` back into the repository. Netlify still gets pinged when the repository is updated, but skips the `npm run build` step on their end. This significantly reduces the number of build minutes required.
+#### Rolling Your Own
 
-**TLDR**: use the [`github-action-publishing`](https://github.com/georgemandis/bubo-rss/tree/github-action-publishing) branch for now if you'd prefer to use GitHub Actions.
+If you already have a server running Linux and some command-line experience it might be simpler to setup a [cron job](https://en.wikipedia.org/wiki/Cron).
-
-**Note:** The GitHub Action is setup to build and commit directly to the `master` branch, which is not the best practice. I'd suggest creating a separate branch to checkout and commit changes to in the action. You could then specify that same branch as the one to checkout and publish on Netlify.
 
 ## Support
 
-If you found this useful please consider sponsoring me or this project. If you'd rather run this on your own server please consider using one of these affiliate links to setup a micro instance on [Linode](https://www.linode.com/?r=8729957ab02b50a695dcea12a5ca55570979d8b9), [Digital Ocean](https://m.do.co/c/31f58d367777) or [Vultr](https://www.vultr.com/?ref=8403978).
+If you found this useful please consider sponsoring me or this project. 
+
+If you'd rather run this on your own server please consider using one of these affiliate links to setup a micro instance on [Linode](https://www.linode.com/?r=8729957ab02b50a695dcea12a5ca55570979d8b9), [Digital Ocean](https://m.do.co/c/31f58d367777) or [Vultr](https://www.vultr.com/?ref=8403978).
 
 ## Showcase