docs: Reorganize documentation with new reference and explanation sections (#176)

Co-authored-by: Claude <noreply@anthropic.com>

docs/how-to/configure-short-length.md

@@ -0,0 +1,45 @@
+# Configure the length of short SHA values
+
+Set a specific length for shortened commit SHA values instead of letting Git determine it automatically.
+
+## Usage
+
+```yaml
+steps:
+  - name: Inject enhanced GitHub environment variables
+    uses: rlespinasse/github-slug-action@v5
+    with:
+      short-length: 7
+```
+
+## Common values
+
+| Value | Use case |
+| ----- | -------- |
+| _(empty)_ | Let Git decide based on repository size (default) |
+| `7` | Common "small repository" length |
+| `8` | Reproduce `v3` action behaviour |
+| `4` | Minimum allowed length |
+
+## Letting Git decide (default)
+
+When `short-length` is left empty, the action uses Git's [`git rev-parse --short`][git-revparse] behaviour. The length depends on the size of your repository and may change over time as the repository grows.
+
+> [!WARNING]
+> If you leave `short-length` empty, you need to checkout the source first so Git can determine the length:
+>
+> ```yaml
+> steps:
+>   - uses: actions/checkout@v6
+>   - uses: rlespinasse/github-slug-action@v5
+> ```
+>
+> Without a checkout step, the action falls back to the effective value of the [`core.abbrev`][git-core-abbrev] Git configuration variable, or `7` if unavailable.
+
+## See also
+
+- [Inputs reference](../reference/inputs.md) for the full specification
+- [SHORT transformation](../explanation/slug-transformation-rules.md#short-transformation) for how short values are computed
+
+[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength
+[git-core-abbrev]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreabbrev

docs/how-to/configure-slug-maxlength.md

@@ -0,0 +1,33 @@
+# Configure the maximum length for slug values
+
+Change the maximum length of slugified values. The default is 63 characters (the DNS label length limit).
+
+## Usage
+
+```yaml
+steps:
+  - name: Inject enhanced GitHub environment variables
+    uses: rlespinasse/github-slug-action@v5
+    with:
+      slug-maxlength: 80
+```
+
+## Disable the length limit
+
+Set `slug-maxlength` to `"nolimit"` to disable truncation entirely:
+
+```yaml
+steps:
+  - name: Inject enhanced GitHub environment variables
+    uses: rlespinasse/github-slug-action@v5
+    with:
+      slug-maxlength: nolimit
+```
+
+> [!WARNING]
+> The `slug-maxlength` input must not be empty. If left empty, the action will fail during preflight validation.
+
+## See also
+
+- [Inputs reference](../reference/inputs.md) for the full specification
+- [Why 63 characters?](../explanation/slug-transformation-rules.md#why-63-characters) for the rationale behind the default

docs/how-to/migrate-v3-to-v4.md

@@ -0,0 +1,30 @@
+# Migrate from v3 to v4
+
+The main breaking change in v4 is that **short SHA length** is now determined by Git instead of being fixed at 8 characters.
+
+## What changed
+
+Since v4, Git manages the short variables using [`git rev-parse`][git-revparse] behaviour. The length of a short SHA depends on the size of your repository and can change over time as the repository grows.
+
+## How to migrate
+
+To reproduce the previous fixed-length behaviour, set `short-length` to `8`:
+
+```yaml
+steps:
+  - name: Inject enhanced GitHub environment variables
+    uses: rlespinasse/github-slug-action@v5
+    with:
+      short-length: 8 # Same as v3 and before
+```
+
+Other options:
+
+- Set `7` to reproduce small repository behaviour
+- Leave empty to let Git decide (recommended)
+
+> [!WARNING]
+> The minimum length is `4`. The default is the effective value of the [`core.abbrev`][git-core-abbrev] Git configuration variable.
+
+[git-revparse]: https://git-scm.com/docs/git-rev-parse#Documentation/git-rev-parse.txt---shortlength
+[git-core-abbrev]: https://git-scm.com/docs/git-config#Documentation/git-config.txt-coreabbrev

docs/how-to/migrate-v4-to-v5.md

@@ -0,0 +1,30 @@
+# Migrate from v4 to v5
+
+The main breaking change in v5 is that **GITHUB_REF_NAME** slug variables now match GitHub's native behaviour on `pull_request*` events.
+
+## What changed
+
+Before v5, the action overrode `GITHUB_REF_NAME` to always contain the branch name, even on pull request events. Starting with v5, `GITHUB_REF_NAME` on pull request events contains `<PR-number>/merge` (matching GitHub's native behaviour). Read the [full story][issue-104].
+
+## How to migrate
+
+If you used `GITHUB_REF_NAME_SLUG` to get the branch name on pull request events, switch to `GITHUB_REF_POINT_SLUG`:
+
+```yaml
+steps:
+  - name: Inject enhanced GitHub environment variables
+    uses: rlespinasse/github-slug-action@v5
+  - run: |
+      echo "Branch Name: ${GITHUB_REF_POINT}"
+    shell: bash
+```
+
+`GITHUB_REF_POINT` provides the branch name on pull request events (via `GITHUB_HEAD_REF`) and the ref name on all other events (via `GITHUB_REF_NAME`). All slug suffixes are available: `GITHUB_REF_POINT_SLUG`, `GITHUB_REF_POINT_SLUG_URL`, etc.
+
+## Expression syntax
+
+- `${{ env.GITHUB_REF_POINT }}` and `$GITHUB_REF_POINT` both serve the action's behaviour
+- `${{ env.GITHUB_REF_NAME }}` serves the action's behaviour
+- `$GITHUB_REF_NAME` serves GitHub Action's native behaviour
+
+[issue-104]: https://github.com/rlespinasse/github-slug-action/issues/104

docs/how-to/troubleshooting.md

@@ -0,0 +1,56 @@
+# Troubleshooting
+
+## One of the environment variables doesn't work as intended
+
+> [!WARNING]
+> When you set a custom environment variable, you [cannot use any of the default environment variable names][naming-conventions]. For a complete list of these, see [Default environment variables][default-environment-variables]. **If you attempt to override the value of one of these default environment variables, the assignment is ignored.**
+
+If a variable starts to be used as a default environment variable by GitHub, the behaviour may differ depending on how you reference it:
+
+- `${{ env.GITHUB_AWESOME_VARIABLE }}` serves the behaviour of this action
+- `$GITHUB_AWESOME_VARIABLE` serves the behaviour of GitHub Actions
+
+If both expressions return the same value, the variable is not affected. Use the [`prefix` input](use-prefix.md) to avoid this issue entirely.
+
+> [!IMPORTANT]
+> If detected, the maintainers of this action will choose the best course of action depending on the impact.
+
+## An action could not be found at the URI
+
+If your workflow fails on the `Set up job` task with this kind of log:
+
+```text
+Download action repository 'rlespinasse/github-slug-action@GIT_REFERENCE'
+##[error]An action could not be found at the URI 'https://api.github.com/repos/rlespinasse/github-slug-action/tarball/GIT_REFERENCE'
+```
+
+If the `GIT_REFERENCE` value is:
+
+- `v4.x` or after: following the [end-of-life for a branch](../../SECURITY.md#end-of-life-of-a-branch) security process, this branch may have been deleted.
+- `master`: this branch no longer exists. Read more on the corresponding issue ([EOL issue][issue-15]).
+
+Use the current **major tag** `v5` or a specific version tag (see [releases][releases]) to fix your workflow.
+
+## Short variables are empty or have unexpected length
+
+If `GITHUB_SHA_SHORT` is empty or shorter than expected, ensure you have checked out your repository before the action runs:
+
+```yaml
+steps:
+  - uses: actions/checkout@v6
+  - uses: rlespinasse/github-slug-action@v5
+```
+
+Without a checkout, Git cannot determine the optimal short length for your repository. Alternatively, set a fixed `short-length` to avoid depending on the checkout:
+
+```yaml
+steps:
+  - uses: rlespinasse/github-slug-action@v5
+    with:
+      short-length: 7
+```
+
+[naming-conventions]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#naming-conventions-for-configuration-variables
+[default-environment-variables]: https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables
+[issue-15]: https://github.com/rlespinasse/github-slug-action/issues/15
+[releases]: https://github.com/rlespinasse/github-slug-action/releases

docs/how-to/use-prefix.md

@@ -0,0 +1,26 @@
+# Use a prefix for generated variables
+
+Add a prefix to all generated environment variables to avoid naming conflicts with [GitHub's default environment variables](https://docs.github.com/en/actions/reference/workflows-and-actions/variables#default-environment-variables).
+
+## Usage
+
+```yaml
+steps:
+  - name: Inject enhanced GitHub environment variables
+    uses: rlespinasse/github-slug-action@v5
+    with:
+      prefix: CI_
+```
+
+With this configuration, variables are named `CI_GITHUB_REPOSITORY_SLUG`, `CI_GITHUB_REF_SLUG`, `CI_GITHUB_SHA_SHORT`, etc.
+
+## When to use a prefix
+
+- When a variable name collides with a GitHub default environment variable (the assignment would be silently ignored without a prefix)
+- When you want to distinguish slug variables from other environment variables in your workflow
+- As a preventive measure against future GitHub environment variable additions
+
+## See also
+
+- [Inputs reference](../reference/inputs.md) for the full `prefix` input specification
+- [Troubleshooting](troubleshooting.md#one-of-the-environment-variables-doesnt-work-as-intended) for details on variable name collisions

docs/how-to/use-slugs-in-urls.md

@@ -0,0 +1,36 @@
+# Use slug variables in URLs
+
+Use `SLUG_URL` variables (not `SLUG`) when building URLs, because `SLUG_URL` also replaces dots and underscores with hyphens, making values safe for subdomains and URL paths.
+
+## As a subdomain
+
+```yaml
+steps:
+  - uses: actions/checkout@v6
+  - uses: rlespinasse/github-slug-action@v5
+  - run: |
+      ./deploy-application.sh --url "https://${{ env.GITHUB_REF_SLUG_URL }}.staging.app.example.com"
+```
+
+For a branch `feat/new_feature`, this produces `https://feat-new-feature.staging.app.example.com`.
+
+## As a URL path segment
+
+```yaml
+steps:
+  - uses: actions/checkout@v6
+  - uses: rlespinasse/github-slug-action@v5
+  - run: |
+      ./deploy-application.sh --url "https://staging.app.example.com/${{ env.GITHUB_REF_SLUG_URL }}"
+```
+
+## Why SLUG_URL instead of SLUG?
+
+The `SLUG` transformation preserves `.` and `_` characters. In a subdomain like `v1.0.0.staging.example.com`, the dots from the version tag would create invalid DNS resolution. `SLUG_URL` replaces them: `v1-0-0.staging.example.com`.
+
+See [Slug transformation rules](../explanation/slug-transformation-rules.md#slug_url-transformation) for the full comparison.
+
+## See also
+
+- [Full example workflow](../../examples/url-use.yml)
+- [Variable reference](../reference/variables.md) for all available `SLUG_URL` variables