README
Tweet to Markdown
A command line tool to quickly save tweets as Markdown.
Report a Bug
·
Request a Feature
About The Project
This command line tool allows you to quickly save a tweet in Markdown format. This is great for Zettelkasten note-taking or any other commonplace notebook, vade mecum, Obsidian, Roam, Foam, &c. It is built on the new Twitter v2 API.
Installing
⚠ You'll need to have Node.js of at least v10.x to use this tool.
You can install this CLI tool easily by running
yarn global add tweet-to-markdown
or
npm install --global tweet-to-markdown
You can also run it without installing:
npx tweet-to-markdown
Setup
To use this tool, you have two options:
- Sign up for a free API key from https://ttm.kbravh.dev (new in v2.0.0)
- Sign up for a bearer token through the Twitter Developer dashboard
Getting a free API key from https://ttm.kbravh.dev is the easiest method of using this plugin, as you won't have to go through Twitter's developer application process. Their application is tedious, and they don't always approve requests. However, you are more than welcome to follow the guide below to retrieve your own bearer token from Twitter. This will give you the most control, freedom, and security over your usage.
Free TTM API key
You can sign up for a free API key at https://ttm.kbravh.dev by signing in with either your GitHub or Twitter account and heading to your account page. Once you sign in and retrieve your API key from your account page, either store it in the environment variable TTM_API_KEY or pass it to the command line tool with the -b (--bearer) flag with each call.
Twitter Developer bearer token
To get a bearer token from Twitter, you'll need to set up an application on the Twitter developer dashboard. For a guide on doing so, see Getting a bearer token. Once you have the bearer token, either store it in the environment variable TWITTER_BEARER_TOKEN or pass it to the command line tool with the -b (--bearer) flag with each call.
Usage
Grabbing a tweet is as easy as calling the ttm command and passing in the tweet URL.
ttm -b <bearer token> https://twitter.com/JoshWComeau/status/1213870628895428611
# Tweet saved as JoshWComeau - 1213870628895428611.md
The tweet will be saved to a Markdown file in the current directory. Here's how the tweet will look:
Any attached images, polls, and links will also be linked and displayed in the file.
Options
There are many options to customize how this tool works. It is highly recommended to find the options you need and set up an alias in your terminal.
For example on Mac or Linux, you can define an alias with your options like so:
alias ttm="ttm -p $HOME/notes --assets --quoted"
For Windows, have a look at DOSKEY.
Copy to Clipboard
What if you want to just copy the Markdown to the clipboard instead of saving to a file? Why, it's as simple as just passing the -c (--clipboard) flag.
ttm -c https://twitter.com/JoshWComeau/status/1213870628895428611
#Tweet copied to the clipboard.
Quoted tweets
If you would like to include quoted tweets, pass the -q (--quoted) flag. This is disabled by default because a separate request has to be made to fetch the quoted tweet.
ttm <tweet url> -q
Tweet threads
To capture an entire tweet thread, use the -t (--thread) flag and pass the URL of the last tweet in the thread.
Nota bene: this will make a separate network request for each tweet.
ttm <last tweet url> -t
Custom File Name
In order to save the tweet with a custom filename, pass the desired name to the --filename flag. You can use the variables [[name]], [[handle]], [[text]], and [[id]] in your filename, which will be replaced according to the following chart. The file extension .md will also be added automatically.
| Variable | Replacement |
|---|---|
| [[handle]] | The user's handle (the part that follows the @ symbol) |
| [[name]] | The user's name |
| [[id]] | The unique ID assigned to the tweet |
| [[text]] | The entire text of the tweet (truncated to fit OS filename length restrictions) |
ttm <tweet url> --filename "[[handle]] - Favicon versioning".
# Tweet saved to JoshWComeau - Favicon versioning.md
If the file already exists, an error will be thrown unless you pass the -f (--force) flag to overwrite the file.
Custom File Path
To save the tweet to a place other than the current directory, pass the location to the -p (--path) flag. If this path doesn't exist, it will be recursively created.
ttm <tweet url> -p "./tweets/"
# Tweet saved to ./tweets/JoshWComeau - 1213870628895428611.md
Tweet Metrics
If you'd also like to record the number of likes, retweets, and replies the tweet has, pass the -m (--metrics) flag. This will save those numbers in the frontmatter of the file.
ttm <tweet url> -m
---
author: Josh ✨
handle: @JoshWComeau
likes: 993
retweets: 163
replies: 24
---
Save Images Locally
Want to really capture the entire tweet locally? You can pass the -a (--assets) flag to download all the tweet images as well, instead of just linking to the images on the web. If the tweet is ever deleted or Twitter is unavailable, you'll still have your note.
ttm <tweet url> -a
Tweet images will be automatically saved to ./tweet-assets. If you'd like to save the assets to a custom directory, use the --assets-path flag and pass in the directory.
ttm <tweet url> -a --assets-path "./images"
Nota bene: Unfortunately, there is currently not a way to save gifs or videos from tweets using the v2 API.
Contributing
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
- Fork the Project
- Create your Feature Branch (
git checkout -b feature) - Commit your Changes (
git commit -m "Add a cool feature") - Push to the Branch (
git push origin feature) - Open a Pull Request
License
This project is licensed under the MIT License - see the LICENSE file for details
Contact
Karey Higuera - @kbravh - karey.higuera@gmail.com
Project Link: https://github.com/kbravh/tweet-to-markdown