documentation-actions

Reusable GitHub Actions and reusable workflows for Docusaurus documentation sites and awesome-list repositories.

Extracted from duplicated automation across:

• LLazyEmail/awesome-email-marketing
• LLazyEmail/awesome-newsletters
• LLazyEmail/documentation

Modeled on LLazyEmail/email-template-workflows.

Pin LLazyEmail/documentation-actions@v1 once the first GitHub Release exists (auto-created when a release PR merges). Draft adoption PRs may use @main only during the adoption window. For the strongest supply-chain guarantee, pin a full commit SHA and keep it current with Renovate.

Marketplace

The repository root contains an action.yml so the suite can be listed on the GitHub Marketplace. After the next release, check Publish this Action to the GitHub Marketplace when drafting the release.

The root action is an umbrella composite that optionally runs markdownlint, a soft-fail lychee check, and a Docusaurus build. Specialized composite actions (under actions/<name>/) and reusable workflows (under .github/workflows/) continue to be used by path and are not listed separately on the Marketplace.

- uses: LLazyEmail/documentation-actions@v1
  with:
    run-markdownlint: true
    markdownlint-globs: |
      README.md
      website/docs/**/*.md
    run-lychee: true
    lychee-args: >-
      --verbose --no-progress --accept 200,204,206,403,429
      README.md 'website/docs/**/*.md'
    run-build: true
    working-directory: website

Quick start

# PR test build for a Docusaurus site under website/
jobs:
  test-deploy:
    uses: LLazyEmail/documentation-actions/.github/workflows/reusable-docusaurus-test-deploy.yml@main
    with:
      working-directory: website
      cache-dependency-path: website/package-lock.json

# Soft-fail lychee with a job summary
jobs:
  lychee:
    uses: LLazyEmail/documentation-actions/.github/workflows/reusable-link-check.yml@main
    with:
      args: >-
        --verbose --no-progress --accept 200,204,206,403,429
        README.md 'website/docs/**/*.md'

More copy-paste callers live in examples/.

Actions and workflows

The inventory is append-only in docs/actions-index.md: each action PR adds exactly one new table row at the end and never reorders or edits other rows. That keeps stacked PRs from conflicting on the README.

Composite actions live only under actions/<name>/ (plus their reusable workflow, example, and test). Do not scatter related files across shared directories in a way that forces every PR to touch the same lines.

Usage snippets

Star request

on:
  pull_request_target:
    types: [opened]
permissions:
  pull-requests: write
jobs:
  comment:
    uses: LLazyEmail/documentation-actions/.github/workflows/reusable-star-request.yml@main

Awesome-list checks

jobs:
  checks:
    uses: LLazyEmail/documentation-actions/.github/workflows/reusable-awesome-list-checks.yml@main
    with:
      checks: entry-format,duplicate-links,sorted-sections

Auto-rebase (consumers)

on:
  schedule:
    - cron: '0 */6 * * *'
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
jobs:
  rebase:
    uses: LLazyEmail/documentation-actions/.github/workflows/reusable-auto-rebase-prs.yml@main

This repository also ships an early in-repo .github/workflows/auto-rebase-prs.yml so the draft stack stays current before the composite action merges.

Git push with rebase retry

- uses: LLazyEmail/documentation-actions/actions/git-push-retry@v1
  with:
    commit-paths: CHANGELOG.md website/src/data/changelog.json
    commit-message: 'chore(changelog): regenerate after merged pull request'

Commit-back reusable workflows (changelog, docs-index, catalog-api) already use this composite.

Build annotations and PR comment

jobs:
  test-deploy:
    uses: LLazyEmail/documentation-actions/.github/workflows/reusable-docusaurus-test-deploy.yml@v1
    with:
      working-directory: website
      cache-dependency-path: website/package-lock.json
      # annotate-log: true   # default
      pr-comment: true      # optional; grant pull-requests: write on the caller
    secrets: inherit

Broken links, anchors, and [WARNING] / [ERROR] lines from the Docusaurus build become check annotations and a job-summary section automatically.

Docs CI umbrella

jobs:
  docs-ci:
    uses: LLazyEmail/documentation-actions/.github/workflows/reusable-docs-ci.yml@v1
    with:
      run-markdownlint: true
      markdownlint-globs: |
        README.md
        website/docs/**/*.md
      run-lychee: true
      lychee-args: >-
        --verbose --no-progress --accept 200,204,206,403,429
        README.md 'website/docs/**/*.md'
      # run-build: true  (default)
    secrets: inherit

Keep triggers on the caller; toggle jobs with boolean inputs. Full copy-paste: examples/docs-ci.yml.

Adoption

See docs/adoption.md for consumer cut-over notes and docs/design.md for layout conventions.

License

MIT © LLazyEmail