YouTube → Markdown

API / CGI usage

Purpose: This tool produces plain-text Markdown snippets (image + link + title) that are ideal for pasting into GitHub README files, issues, PR comments, and other Markdown-friendly environments.

The CGI endpoint (index.cgi) accepts the following query parameters and returns plain-text Markdown:

• id — YouTube video ID (preferred).
• url — Full YouTube URL (used if id is not provided).
• title — Optional title to use in the Markdown link. If omitted the script will attempt to fetch the YouTube page and scrape the <title>.
• output — Optional. One of markdown (default), json, or html. Use output=json to receive structured output including thumbnail, url, markdown, html, and title.
• caption — Optional. Use caption=1 to include the visible caption (default), or caption=0 to omit it. For backward compatibility the old flags no_caption / no-caption are still accepted and treated as caption=0. The CLI supports --no-caption as a shorthand.
• thumb — Optional. Select the thumbnail to use (shorthand or filename). Accepted values: 0 (default), 1, 2, 3, hq, sd, max / maxres, or a filename like maxresdefault.jpg. For the CLI use --thumb.

Example responses look like:

[![Never Gonna Give You Up](http://img.youtube.com/vi/dQw4w9WgXcQ/0.jpg)](http://www.youtube.com/watch?v=dQw4w9WgXcQ "Never Gonna Give You Up")

curl examples

Using a URL:

curl -s "https://brettterpstra.com/yt-md/api?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

Using an ID:

curl -s "https://brettterpstra.com/yt-md/api?id=dQw4w9WgXcQ"

Provide a custom title (override scraping):

curl -s "https://brettterpstra.com/yt-md/api?url=https://youtu.be/dQw4w9WgXcQ&title=My%20Title"

Request JSON (useful for programmatic consumers):

curl -s "https://brettterpstra.com/yt-md/api?id=dQw4w9WgXcQ&output=json"

Example JSON response:

{
                "thumbnail": "http://img.youtube.com/vi/dQw4w9WgXcQ/0.jpg",
                "url": "http://www.youtube.com/watch?v=dQw4w9WgXcQ",
                "markdown": "[![Never Gonna Give You Up](http://img.youtube.com/vi/dQw4w9WgXcQ/0.jpg)](http://www.youtube.com/watch?v=dQw4w9WgXcQ \"Never Gonna Give You Up\")",
                "html": "<figure class=\\\"yt-thumbnail\\\"><a href=\\\"http://www.youtube.com/watch?v=dQw4w9WgXcQ\\\"><img src=\\\"http://img.youtube.com/vi/dQw4w9WgXcQ/0.jpg\\\" alt=\\\"Never Gonna Give You Up\\\"></a><figcaption class=\\\"yt-caption\\\">Never Gonna Give You Up</figcaption></figure>",
                "title": "Never Gonna Give You Up"
            }

Request HTML without a caption:

curl -s "https://brettterpstra.com/yt-md/api?id=dQw4w9WgXcQ&output=html&caption=0"

Request a specific thumbnail size (thumb parameter):

curl -s "https://brettterpstra.com/yt-md/api?id=dQw4w9WgXcQ&thumb=hq&output=json"
curl -s "https://brettterpstra.com/yt-md/api?id=dQw4w9WgXcQ&thumb=maxresdefault.jpg"

Why this is handy for GitHub

The output is plain Markdown (image linked to the YouTube video with a title). It's designed so you can copy it directly into a GitHub README.md, issue, or pull request comment and have it render as a clickable thumbnail with title.