Guadalupe Cañas-Herrera

Repository Page Troubleshooting

Issue: Repository cards not loading / showing broken images

Symptom: The repositories page looks broken, with missing or failed-to-load images where repository cards should appear.

Cause: The repository page uses external services (primarily github-readme-stats.vercel.app) to generate dynamic repository cards and statistics. These services are free, third-party hosted, and can experience:

This is not a bug in al-folio but a limitation of the external services. See:

Solutions

The best long-term solution is to deploy your own instance of these services. It’s free and takes about 10-15 minutes.

For github-readme-stats:

  1. Fork the repository:
  2. Deploy to Vercel (free):
    • Go to Vercel
    • Sign in with your GitHub account
    • Click “New Project”
    • Import your forked github-readme-stats repository
    • Follow the deployment wizard (accept all defaults)
    • Note your deployment URL (e.g., https://github-readme-stats-yourname.vercel.app)
  3. Update your site configuration:
    • Open _config.yml in your repository
    • Find the external_services section
    • Update the URL:
    external_services:
  github_readme_stats_url: https://github-readme-stats-yourname.vercel.app
  github_profile_trophy_url: https://github-profile-trophy.vercel.app
  4. Commit and push changes: 
    git add _config.yml
git commit -m "config: Use self-hosted github-readme-stats instance"
git push

Your repository cards should now load reliably using your own instance!

For github-profile-trophy (optional):

If you also want to host the trophy service:

  1. Fork github-profile-trophy
  2. Deploy to Vercel (same process as above)
  3. Update github_profile_trophy_url in _config.yml

See: Deployment guide

Option 2: Temporarily Disable Repository Page Features

If you don’t want to deploy your own instance, you can disable specific features:

Disable trophies (in _config.yml):

repo_trophies:
  enabled: false # Change from true to false

Disable the entire repositories page:

Option 3: Wait for Service Recovery

The default github-readme-stats.vercel.app service may recover after some time. However, this is not reliable for production sites.

Checking if Services are Working

You can manually test if the services are accessible:

Test github-readme-stats:

https://github-readme-stats.vercel.app/api?username=YOUR_GITHUB_USERNAME

Test github-profile-trophy:

https://github-profile-trophy.vercel.app/?username=YOUR_GITHUB_USERNAME

Open these URLs in your browser. If they load images, the service is working. If they show errors or timeout, the service is down.

Need Help?

This site is open source. Improve this page.