Awesome Elixir Deploy and Usage Guide

Prerequisites

• Git (2.0+) - for version control
• Node.js (16+) and npm - required for running validation tools locally
• GitHub Account - needed for contributing via pull requests and accessing CI features
• Make (optional) - if the repository includes a Makefile for task automation

Installation

Clone the repository and install validation dependencies:

git clone https://github.com/h4cc/awesome-elixir.git
cd awesome-elixir
npm install

If the project uses specific Elixir-based validation scripts (check for mix.exs):

# Install Elixir dependencies (if applicable)
mix deps.get

Configuration

Environment Variables

For local link checking and CI simulation, set a GitHub token to avoid rate limits:

export GITHUB_TOKEN=ghp_your_personal_access_token

Create a token at GitHub Settings > Developer settings > Personal access tokens (classic) with public_repo scope.

Git Configuration

Ensure your Git identity is set for commits:

git config user.name "Your Name"
git config user.email "your.email@example.com"

Build & Run

Local Validation

Run the awesome-list linter to validate formatting rules:

npm run lint
# Alternative if awesome-lint is installed globally:
npx awesome-lint README.md

Link Verification

Check for dead links in the documentation:

npm run test
# Or directly:
npx markdown-link-check README.md --config .markdown-link-check.json

CI Simulation

Run the same checks executed by GitHub Actions locally:

# If using Make
make test

# Or run the CI script directly
bash .github/workflows/ci.yml  # Check for local simulation scripts

Deployment

This repository deploys automatically through GitHub's infrastructure:

1. Continuous Integration: The .github/workflows/ci.yml automatically validates all pull requests and pushes to main
2. GitHub Pages: The list renders automatically at https://h4cc.github.io/awesome-elixir/ when GitHub Pages is enabled in repository settings (Source: GitHub Actions or Branch: main)

Manual Trigger

To force a CI validation without pushing code:

gh workflow run ci.yml  # Requires GitHub CLI

Troubleshooting

CI Build Failures

Issue: Awesome list must have a table of contents
Solution: Ensure your additions follow the existing alphabetical order and include entries in the TOC section at the top of README.md.

Issue: Link to ... is dead (false positives)
Solution: Some Elixir package repositories may rate-limit or block automated requests. Verify manually:

curl -I https://github.com/username/repo

If accessible, the maintainer can re-run the CI job.

Issue: Merge conflicts when contributing
Solution: This is a high-traffic repository. Always work in a feature branch and rebase before submitting:

git fetch upstream
git rebase upstream/main

Validation Errors

Issue: List item description must start with description
Solution: Ensure entries follow the format: * [package](url) - Description starting with capital letter.

Issue: npm install failures
Solution: Clear cache and use exact versions:

rm -rf node_modules package-lock.json
npm ci