feat(docs): add table of contents to README

[jsjoeio]

This PR adds a table of contents to the README (auto-generated using github-markdown-toc).

It also makes the heading of the README look a little better.

Resolves one task from #1024

Gif

Here's the package markdown-toc in action:

UPDATE
I automated it by adding a pre-push hook that runs this script:

"generate-toc": "markdown-toc -i ./README.md && git add README.md && git commit -m 'chore: update docs'"

It's super fast! And I did pre-push because I figured pre-commit might be too much.

[jsjoeio]

(friendly) bump @johnnyreilly

[johnnyreilly]

Sorry I missed this Joe - been snowed! This looks super cool!!

I actually didn't realize you could include html in a markdown file. I must admit to a a gut feeling of "but it's HTML in a markdown file - outrageous!". But I can get past that 😉

So what's the process for regeneration?

[jsjoeio]

No worries at all!

😂 Fair point!

So now that you're asking, I'm second-questioning the package/tool I used...It looks like this one doctoc might be easier to set up as a git hook so then the TOC always stays up to date?

Let me know if you think that would be worth it, and I'll make some time to investigate this weekend.

[johnnyreilly]

Oh that sounds great! Yeah automating is always a good goal and so if you are game for looking into that I'd be super grateful!

[jsjoeio]

@johnnyreilly I got it working! 😄

Check it out. Updated the description. Open to feedback if you have any opinions on anything too!

[johnnyreilly]

Awesome! I'll try and take a look this weekend. Ping me if I forget!

[jsjoeio]

@johnnyreilly friendly ping 😄

[johnnyreilly]

Looks awesome! So this regenerates what sits between <!-- toc --> and <!-- tocstop --> upon prepush? Nice!

[johnnyreilly]

There might be an issue with this - see linked issue

[jsjoeio]

Hoping to address in #1045