This is just a little 30-minute project I made for my own use, but figured I’d share. It simply takes a YouTube URL and converts it to GitHub-friendly Markdown for use in READMEs, wikis, and PR comments.
GitHub doesn’t allow for <iframe>s, so you can’t actually embed a YouTube video in a README. You can, however, easily embed a thumbnail and link it to the video. This little API does just that. Sure, it’s built with GitHub in mind, but it’s useful in any situation where you can’t use an actual embed but want to include a YouTube video.
You can play around with the API at https://brettterpstra.com/yt-md, which has full documentation and live testing.
The endpoint for the API is:
https://brettterpstra.com/yt-md/api
Include a ?url= (full YouTube URL) or ?id= (just a video ID) parameter, and it will generate the Markdown for you. You can also include &output=json or &output=html to get JSON or HTML output. Add &caption=0 to avoid including a caption in the HTML.
Here are a few quick examples you can run from the command line using curl. Replace the video ID in the examples with your own.
Basic: request Markdown for a video ID:
[iterm “curl -s ‘https://brettterpstra.com/yt-md/api?id=w1LuV82l0vs’”]
Using a full YouTube URL:
[iterm “curl -s ‘https://brettterpstra.com/yt-md/api?url=https://www.youtube.com/watch?v=w1LuV82l0vs’”]
JSON output (pretty-print with jq):
| [iterm “curl -s ‘https://brettterpstra.com/yt-md/api?id=w1LuV82l0vs&output=json’ | jq ‘.’”] |
HTML output without a caption (show the first few lines):
| [iterm “curl -s ‘https://brettterpstra.com/yt-md/api?id=w1LuV82l0vs&output=html&caption=0’ | sed -n ‘1,3p’”] |
Request a specific thumbnail size (maxres):
| [iterm “curl -s ‘https://brettterpstra.com/yt-md/api?id=w1LuV82l0vs&thumb=maxres’ | sed -n ‘1,1p’”] |
[paywall “Bonus CLI and Shortcut”]
This can be easily used from the command line with this script:
[gist f048fbe18a59d9208d46f20cc829345a]
Save this in your path as yt-md and make it executable (chmod +x path/to/yt-md).
The script takes a YouTube URL as an argument and accepts --title "FORCED TITLE", --output, which can be markdown (default), json, or html, and --no-caption which avoids including a caption in the HTML output.
I also whipped up a shortcut that can run as a Service or take input from the clipboard:
YouTube to Markdown Apple Shortcut
Lastly, here’s a TextBlaze folder of actions for creating a basic Markdown snippet (Mdyt), or for generating Markdown or HTML with proper title scraping (/ytmd or /ythtml).
YouTube Markdown for TextBlaze
[endpaywall]
Leave a Reply