Skip to content

DenverCoder1/github-readme-youtube-cards

Use this GitHub action with your project
Add this Action to an existing workflow or create a new one
View on Marketplace

Repository files navigation

GitHub Readme YouTube Cards

Workflow for displaying recent YouTube videos as SVG cards in your readme

Basic Usage

  1. Add the following snippet to your markdown file where you want the cards to appear.
<!-- BEGIN YOUTUBE-CARDS -->
<!-- END YOUTUBE-CARDS -->
  1. In your repo, create a .github folder and inside create a folder named workflows if it does not exist. Then create a file in your .github/workflows/ folder and give it a name such as youtube-cards.yml with the following contents.
name: GitHub Readme YouTube Cards
on:
  schedule:
    # Runs every hour, on the hour
    - cron: "0 * * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    # Allow the job to commit to the repository
    permissions:
      contents: write
    # Run the GitHub Readme YouTube Cards action
    steps:
      - uses: DenverCoder1/github-readme-youtube-cards@main
        with:
          channel_id: UCipSxT7a3rn81vGLw9lqRkg
  1. Make sure to change the channel_id to your YouTube channel ID.

  2. The cron expression in the example above is set to run at the top of every hour. The first time, you may want to trigger the workflow manually.

  3. You're done! Star the repo and share it with friends! ⭐

See below for advanced configuration.

Live Example

GitHub Star Swag Unboxing and Giveaways How To Self-Host GitHub Readme Streak Stats on Vercel Automatically Deploy to Fly.io with GitHub Actions Hosting a Python Discord Bot for Free with Fly.io Making a Wordle Clone Discord Bot with Python (Nextcord) Run Open Source Code in Seconds with GitPod

Advanced Configuration

See action.yml for full details.

Check out the Wiki for frequently asked questions.

Inputs

Option Description Default
channel_id The channel ID to use for the feed πŸ“Ί ""
playlist_id The playlist ID to use for the feed πŸ“Ί ""
lang The locale for views and timestamps πŸ’¬ "en"
comment_tag_name The text in the comment tag for replacing content "YOUTUBE-CARDS"
youtube_api_key The API key to use for features marked with πŸ”‘ ""
max_videos The maximum number of videos to display 6
base_url The base URL to use for the cards "https://ytcards.demolab.com/"
card_width The width of the SVG cards in pixels 250
border_radius The border radius of the SVG cards 5
background_color The background color of the SVG cards "#0d1117"
title_color The color of the title text "#ffffff"
stats_color The color of the stats text "#dedede"
theme_context_light JSON object with light mode colors 🎨 "{}"
theme_context_dark JSON object with dark mode colors 🎨 "{}"
max_title_lines The maximum number of lines to use for the title 1
show_duration πŸ”‘ Whether to show the duration of the videos "false"
author_name The name of the commit author "GitHub Actions"
author_email The email address of the commit author "41898282+github-actions[bot]@users.noreply.github.com"
commit_message The commit message to use for the commit "docs(readme): Update YouTube cards"
readme_path The path to the Markdown or HTML file to update "README.md"
output_only Whether to skip writing to the readme file "false"
output_type The output syntax to use ("markdown" or "html") "markdown"

πŸ“Ί A Channel ID or Playlist ID is required. See How to Locate Your Channel ID in the wiki for more information. To filter videos by type such as removing shorts or showing only popular videos, see How to Filter Videos by Type.

πŸ”‘ Some features require a YouTube API key. See Setting Up the Action with a YouTube API Key in the wiki for more information.

🎨 See Setting Theme Contexts for Light and Dark Mode in the wiki for more information.

πŸ’¬ See this directory for a list of locales with the word "views" translated. The timestamps will still be translated using Babel even if a translation file is not present. See issue #48 for info on contributing translations.

Outputs

Output Description
markdown The generated Markdown or HTML used for updating the README file
committed Whether the action has created a commit (true or false)
commit_long_sha The full SHA of the commit that has just been created
commit_sha The short 7-character SHA of the commit that has just been created
pushed Whether the action has pushed to the remote (true or false)

See Using the Markdown as an Action Output for more information.

Example Workflow

This is an advanced example showing the available options. All options are optional except channel_id.

name: GitHub Readme YouTube Cards
on:
  schedule:
    # Runs every hour, on the hour
    - cron: "0 * * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    # Allow the job to commit to the repository
    permissions:
      contents: write
    # Run the GitHub Readme YouTube Cards action
    steps:
      - uses: DenverCoder1/github-readme-youtube-cards@main
        with:
          channel_id: UCipSxT7a3rn81vGLw9lqRkg
          lang: en
          comment_tag_name: YOUTUBE-CARDS
          youtube_api_key: ${{ secrets.YOUTUBE_API_KEY }} # Configured in Actions Secrets (see Wiki)
          max_videos: 6
          base_url: https://ytcards.demolab.com/
          card_width: 250
          border_radius: 5
          background_color: "#0d1117"
          title_color: "#ffffff"
          stats_color: "#dedede"
          theme_context_light: '{ "background_color": "#ffffff", "title_color": "#24292f", "stats_color": "#57606a" }'
          theme_context_dark: '{ "background_color": "#0d1117", "title_color": "#ffffff", "stats_color": "#dedede" }'
          max_title_lines: 2
          show_duration: true # Requires YouTube API Key (see Wiki)
          author_name: GitHub Actions
          author_email: 41898282+github-actions[bot]@users.noreply.github.com
          commit_message: "docs(readme): Update YouTube cards"
          readme_path: README.md
          output_only: false
          output_type: markdown

Example Playlist Workflow

This is an example workflow for using a playlist instead of a channel.

name: GitHub Readme YouTube Cards
on:
  schedule:
    # Runs every hour, on the hour
    - cron: "0 * * * *"
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    # Allow the job to commit to the repository
    permissions:
      contents: write
    # Run the GitHub Readme YouTube Cards action
    steps:
      - uses: DenverCoder1/github-readme-youtube-cards@main
        with:
          playlist_id: PL9YUC9AZJGFFAErr_ZdK2FV7sklMm2K0J

Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request if you have a way to improve this project.

Make sure your request is meaningful and you have tested the app locally before submitting a pull request.

Please check out our contributing guidelines for more information on how to contribute to this project.

πŸ™‹β€β™‚οΈ Support

πŸ’™ If you like this project, give it a ⭐ and share it with friends!

Youtube Sponsor with Github

β˜• Buy me a coffee