rewrited by raise

rlespinasse · Nov 3, 2024 · 4183c71 · 4183c71
1 parent f6c158d
commit 4183c71
Show file tree

Hide file tree

Showing 27 changed files with 1,223 additions and 716 deletions.
diff --git a/README.md b/README.md
@@ -1,116 +1,97 @@
 # GitHub Slug Action
 
-A powerful GitHub Action that exposes slug/short versions of GitHub environment variables for enhanced workflow management.
+Generate slug and url-safe variables for your GitHub Actions workflows based on GitHub environment variables.
 
-## Features
-
-- Converts environment variables to slug format (lowercase, URL-friendly)
-- Provides URL-safe versions of variables
-- Generates shortened versions of commit SHAs
-- Maintains case-sensitive options
-- Supports custom prefixes and length configurations
-
-## Quick Start
-
-```yaml
-- name: Enhanced GitHub environment variables
-  uses: rlespinasse/github-slug-action@v5
-```
-
-## Configuration Options
-
-### Basic Usage
-
-```yaml
-- name: Enhanced GitHub environment variables
-  uses: rlespinasse/github-slug-action@v5
-```
-
-### With Custom Prefix
-
-```yaml
-- name: Enhanced GitHub environment variables
-  uses: rlespinasse/github-slug-action@v5
-  with:
-    prefix: CI_
-```
-
-### With Custom Slug Length
-
-```yaml
-- name: Enhanced GitHub environment variables
-  uses: rlespinasse/github-slug-action@v5
-  with:
-    slug-maxlength: 80  # Use 'nolimit' for unlimited length (Default: 63)
-```
-
-### With Custom Short Length
+## 🚀 Quick Start
 
 ```yaml
-- name: Enhanced GitHub environment variables
-  uses: rlespinasse/github-slug-action@v5
-  with:
-    short-length: 7  # Default: Git-determined, use 8 for v3.x compatibility
+steps:
+  - uses: rlespinasse/github-slug-action@v5
+  - name: Print slug variables
+    run: |
+      echo "Repository: ${{ env.GITHUB_REPOSITORY_SLUG }}"
+      echo "Branch Name: ${{ env.GITHUB_REF_NAME }}"
+      echo "Branch Ref: ${{ env.GITHUB_REF_SLUG }}"
+      echo "SHA: ${{ env.GITHUB_SHA_SHORT }}"
 ```
 
-## Available Variables
-
-### Enhanced Variables
-
-- `GITHUB_REF_NAME`: Reference name (branch/tag)
+## 📖 Table of Contents
 
-### Partial Variables
+- [GitHub Slug Action](#github-slug-action)
+  - [🚀 Quick Start](#-quick-start)
+  - [📖 Table of Contents](#-table-of-contents)
+  - [✨ Features](#-features)
+  - [🔧 Usage](#-usage)
+  - [📋 Available Variables](#-available-variables)
+  - [💡 Examples](#-examples)
+    - [Branch Deployment](#branch-deployment)
+  - [📚 Documentation](#-documentation)
+  - [🤝 Contributing](#-contributing)
+  - [📄 License](#-license)
 
-- `GITHUB_REPOSITORY_OWNER_PART`
-- `GITHUB_REPOSITORY_NAME_PART`
+## ✨ Features
 
-### Slug Variables
+- Generates clean, URL-safe slugs from GitHub variables
+- Supports Windows and Linux runners
+- Provides multiple variable formats:
+  - Standard slugs
+  - URL-safe slugs
+  - Short SHA versions
+- Zero configuration required
+- Lightweight and fast execution
 
-- `GITHUB_REPOSITORY_SLUG`
-- `GITHUB_REF_SLUG`
-- `GITHUB_HEAD_REF_SLUG`
-- And more...
+## 🔧 Usage
 
-### Short Variables
+1. Add the action to your workflow
+2. Access generated variables in subsequent steps
+3. Use in conditions, environment names, or deployment URLs
 
-- `GITHUB_SHA_SHORT`
-- `GITHUB_EVENT_PULL_REQUEST_HEAD_SHA_SHORT`
+See our [Getting Started Guide](docs/getting-started/quick-start.md) for detailed instructions.
 
-## Troubleshooting
+## 📋 Available Variables
 
-### Common Issues
+| Category   | Original            | Generated Slug           | URL-Safe                     |
+| ---------- | ------------------- | ------------------------ | ---------------------------- |
+| Repository | `GITHUB_REPOSITORY` | `GITHUB_REPOSITORY_SLUG` | `GITHUB_REPOSITORY_SLUG_URL` |
+| Branch/Tag | `GITHUB_REF`        | `GITHUB_REF_SLUG`        | `GITHUB_REF_SLUG_URL`        |
+| SHA        | `GITHUB_SHA`        | `GITHUB_SHA_SHORT`       | -                            |
 
-1. **Short Variable Length Changes**
-   - Use `short-length` input to maintain consistent lengths
-   - Minimum length: 4 characters
+[View all available variables →](docs/variables/overview.md)
 
-2. **Environment Variable Conflicts**
-   - Use prefix to avoid conflicts with GitHub defaults
-   - Check [known conflicts documentation](docs/conflicts.md)
+## 💡 Examples
 
-### Best Practices
+### Branch Deployment
 
-- Use [Dependabot](https://docs.github.com/en/code-security/dependabot) to keep the action updated
-- Always specify version tags (e.g., `@v5`) instead of branch names
-- Test variables in your specific workflow context
+```yaml
+name: Deploy
+on: push
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: rlespinasse/github-slug-action@v5
+      - run: echo "Deploying to ${{ env.GITHUB_REF_SLUG }}"
+```
 
-## Documentation
+[More examples →](docs/guides/)
 
-Detailed documentation available for:
+## 📚 Documentation
 
-- [Slug Variables](docs/slug-variables.md)
-- [URL Variables](docs/slug-url-variables.md)
-- [Short Variables](docs/short-variables.md)
-- [GitHub Variables](docs/github-variables.md)
+- [Getting Started](docs/getting-started/)
+- [Variable Reference](docs/variables/)
+- [Usage Guides](docs/guides/)
+- [Troubleshooting](docs/reference/troubleshooting.md)
 
-## Contributing
+## 🤝 Contributing
 
-Issues and pull requests are welcome! Please check our [contribution guidelines](CONTRIBUTING.md).
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
 
-## License
+## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ---
 
-For detailed examples and advanced usage, visit our [GitHub repository](https://github.com/rlespinasse/github-slug-action).
+⭐ If this action helps you, please consider giving it a star!
+
+[Report Bug](https://github.com/rlespinasse/github-slug-action/issues) · [Request Feature](https://github.com/rlespinasse/github-slug-action/issues)
diff --git a/docs/conflicts.md b/docs/conflicts.md
diff --git a/docs/getting-started/basic-usage.md b/docs/getting-started/basic-usage.md
@@ -0,0 +1,118 @@
+# Basic Usage Guide
+
+## Overview
+
+GitHub Slug Action converts GitHub environment variables into URL-safe slugs. Here's how to use them effectively.
+
+## Core Variables
+
+```yaml
+steps:
+  - uses: rlespinasse/github-slug-action@v5
+  - name: Example Usage
+    run: |
+      # Branch or tag slug
+      echo ${{ env.GITHUB_REF_SLUG }}
+
+      # Repository slug
+      echo ${{ env.GITHUB_REPOSITORY_SLUG }}
+
+      # Short SHA
+      echo ${{ env.GITHUB_SHA_SHORT }}
+```
+
+## Common Patterns
+
+### Environment Names
+
+```yaml
+environment: ${{ env.GITHUB_REF_SLUG }}
+```
+
+### Dynamic URLs
+
+```yaml
+url: https://${{ env.GITHUB_REF_SLUG }}.example.com
+```
+
+### Docker Tags
+
+```yaml
+tags: ${{ env.GITHUB_REPOSITORY_SLUG }}:${{ env.GITHUB_SHA_SHORT }}
+```
+
+## Platform-Specific Usage
+
+### Linux/macOS
+
+```bash
+echo $GITHUB_REF_SLUG
+```
+
+### Windows CMD
+
+```cmd
+echo %GITHUB_REF_SLUG%
+```
+
+### PowerShell
+
+```powershell
+Write-Host $env:GITHUB_REF_SLUG
+```
+
+## Variable Availability
+
+- Variables are available after the action runs
+- Accessible within the same job
+- Must re-run action in different jobs
+- Available in both scripts and workflow files
+
+## Examples
+
+### Pull Request Environments
+
+```yaml
+name: Deploy Preview
+on: pull_request
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: rlespinasse/github-slug-action@v5
+      - name: Deploy
+        run: |
+          deploy --env="pr-${{ env.GITHUB_HEAD_REF_SLUG }}"
+```
+
+### Branch Deployments
+
+```yaml
+name: Deploy Branch
+on: push
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: rlespinasse/github-slug-action@v5
+      - name: Deploy
+        run: |
+          deploy --env="${{ env.GITHUB_REF_SLUG }}"
+```
+
+## Best Practices
+
+- Run the action early in your workflow
+- Use consistent variable references
+- Consider error handling for critical steps
+- Cache slugs for reuse when possible
+
+## Related Resources
+
+- [Available Variables](../variables/overview.md)
+- [Advanced Usage](../guides/advanced-usage.md)
+- [Troubleshooting](../reference/troubleshooting.md)
+
+Need help? [Open an issue](https://github.com/rlespinasse/github-slug-action/issues)