How to Automate README.md Link Checks Using GitHub Actions

Select Language:

Are you tired of manually checking all the links in your README.md file whenever you make updates? Automating this process can save you a lot of time and ensure your links are always working correctly. Here’s a simple step-by-step guide on how to set up GitHub Actions to automatically verify links in your README.md file.

First, you’ll want to create a new workflow for your repository. Inside your GitHub repository, go to the “Actions” tab and click on “New workflow.” You can start from scratch or choose a template, but for this purpose, starting from scratch works best.

Next, make a new file named something like link-check.yml inside the .github/workflows/ directory in your repository. This is where you’ll write the code for your workflow.

In the workflow file, begin by defining the name of your workflow and what triggers it. For example, you can set it to run whenever code is pushed to your main branch or when a pull request is opened. Here’s a simple structure for that:

yaml
name: Check README links

on:
push:
branches:

main
pull_request:
branches:
main

Now, specify the job that will perform the link check. Use an existing tool designed for link verification; one popular choice is the badlinks GitHub Action, which can scan your README.md file for broken links. Here’s how to include it:

yaml
jobs:
link-check:
runs-on: ubuntu-latest
steps:

uses: actions/checkout@v2
name: Check links in README.md
uses: unsplash/link-check@v1
with:
path: README.md

This configuration checks your README.md file each time the workflow is triggered. If broken links are found, the action will fail, and you’ll receive a notification. This lets you quickly fix any issues before merging changes to your main branch.

Finally, commit this workflow file to your repository. Once it’s in place, your GitHub Actions will start automatically checking your README.md links whenever you push updates or submit pull requests.

By setting this up, you’re making sure that your project always has accurate, working links—saving you time and helping maintain professionalism in your documentation. No more manual checks needed, and your README will always stay up-to-date with functioning links!