feat: Front Matter support (#177)

Co-authored-by: Gregor Martynus <[email protected]>

.editorconfig

@@ -0,0 +1,6 @@
+[{*.js,*.json}]
+indent_size = 2
+indent_style = space
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true

.nvmrc

@@ -0,0 +1 @@
+v12

README.md

@@ -24,6 +24,7 @@ For Open Source or event maintainers that share a project twitter account, `twit
 - [How it works](#how-it-works)
   - [The `push` event](#the-push-event)
   - [The `pull_request` event](#the-pull_request-event)
+  - [Advanced tweeting](#advanced-tweeting)
 - [Motivation](#motivation)
 - [License](#license)
 
@@ -102,6 +103,8 @@ This project follows the [all-contributors](https://github.com/all-contributors/
 1. `push` event to publish new tweets
 2. `pull_request` event to validate and preview new tweets
 
+_(Tweets can also be invoked locally by calling the script with the `--file` flag, which can be useful for development. E.g. `TWITTER_ACCESS_TOKEN=... node lib/index.js --file tweets/hello-world.tweet`)_
+
 ### The `push` event
 
 When triggered by the `push` event, the script looks for added `*.tweet` files in the `tweets/` folder or subfolders. If there are any, a tweet for each added tweet file is published.
@@ -112,6 +115,97 @@ If there is no `tweets/` subfolder, the script opens a pull request creating the
 
 For the `pull_request` event, the script handles only `opened` and `synchronize` actions. It looks for new `*.tweet` files in the `tweets/` folder or subfolders. If there are any, the length of each tweet is validated. If one is too long, a failed check run with an explanation is created. If all tweets are valid, a check run with a preview of all tweets is created.
 
+### Advanced tweeting
+
+Beyond tweeting out plain-text tweets, twitter-together also supports creating polls, replying to other tweets, retweeting or quote-retweeting other tweets, threading a chain of tweets, and adding images to tweets.
+
+Polls can be included directly in the body of tweet like so:
+
+```tweet
+What is your favorite color?
+
+( ) Red
+( ) Blue
+( ) Green
+```
+
+All other advanced tweeting features are supporting through defining YAML frontmatter in the tweet file.
+Some frontmatter items can be combined together, where Twitter functionality supports it.
+
+A poll can also be defined in frontmatter, rather than in the tweet body, like so:
+
+```tweet
+---
+poll:
+  - Red
+  - Blue
+  - Green
+---
+
+What is your favorite color?
+```
+
+To reply to another tweet, include the `reply` frontmatter item with the tweet link that you wish to reply to:
+
+```tweet
+---
+reply: https://twitter.com/gr2m/status/1409601188362809349
+---
+
+@gr2m I love your work!
+```
+
+If you want to quote-retweet another tweet, include the `retweet` frontmatter item with the tweet link that you wish to quote-retweet.
+If you'd prefer to just retweet without quoting, don't provide a tweet body after the frontmatter.
+
+```tweet
+---
+retweet: https://twitter.com/gr2m/status/1409601188362809349
+---
+
+twitter-together is awesome!
+```
+
+To include media items with your tweet, include the `media` frontmatter item as an array with each item having a `file` property and an optional `alt` property.
+The `file` property should be the name of a file within the `media` directory of your repository (same level as the `tweets` directory).
+
+_(Note: Although alt text can be set in frontmatter, it is not yet actually passed to Twitter due to library limitations)._
+
+```tweet
+---
+media:
+  - file: cat.jpg
+    alt: A cat
+  - file: dog.jpg
+    alt: A dog
+---
+
+Here are some cute animals!
+```
+
+To thread a chain of tweets, use `---` to delimit each tweet in the file. You can optionally set `threadDelimiter` in the frontmatter to change the delimiter for the next tweet in the thread. Each tweet in a thread supports its own frontmatter.
+
+```tweet
+---
+media:
+  - file: cat.jpg
+    alt: A cat
+  - file: dog.jpg
+    alt: A dog
+---
+
+Here are some cute animals!
+
+---
+---
+poll:
+  - Cat
+  - Dog
+---
+
+Which one is cuter?
+```
+
 ## Motivation
 
 I think we can make Open Source more inclusive to people with more diverse interests by making it easier to contribute other things than code and documentation. I see a particularly big opportunity to be more welcoming towards editorial contributions by creating tools using GitHub’s Actions, Apps and custom user interfaces backed by GitHub’s REST & GraphQL APIs.