Skip to content

Headings options¤

Example action/workflow
compsite action action.yaml
action.yaml
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash
reusable workflow .github/workflows/example_workflow.yml
.github/workflows/example_workflow.yml
name: 'Example workflow'
description: "This key is illegal but will still be parsed"

on:
  workflow_call:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        type: string
      version:
        description: 'Version to deploy'
        required: false
        type: string
        default: 'latest'
      enable-notifications:
        description: 'Whether to send notifications. Requires [`SLACK_WEBHOOK`](#secrets.SLACK_WEBHOOK) to be set.'
        required: false
        type: boolean
        default: false
      parallel-jobs:
        description: 'Number of parallel jobs'
        required: false
        type: number
        default: 1
      configuration:
        description: 'JSON configuration object'
        required: false
        type: string
        default: '{}'
    secrets:
      API_KEY:
        description: 'API key for external service'
        required: true
      DATABASE_URL:
        description: 'Database connection string'
        required: false
      SLACK_WEBHOOK:
        description: 'Slack webhook URL for notifications'
        required: false
    outputs:
      deployment-id:
        description: 'ID of the created deployment'
        value: ${{ jobs.deploy.outputs.deployment-id }}
      deployment-url:
        description: 'URL of the deployment'
        value: ${{ jobs.deploy.outputs.deployment-url }}
      success:
        description: 'Whether the deployment was successful'
        value: ${{ jobs.deploy.outputs.success }}

permissions:
  contents: read
  deployments: write
  pull-requests: write
  issues: read

env:
  DEPLOYMENT_ENVIRONMENT: ${{ inputs.environment }}
  ENABLE_DEBUG: false

jobs:
  validate:
    name: 'Validate Inputs'
    runs-on: ubuntu-latest
    steps:
      - name: Validate environment
        run: |
          echo "Validating environment: ${{ inputs.environment }}"
          if [[ ! "${{ inputs.environment }}" =~ ^(development|staging|production)$ ]]; then
            echo "Error: Invalid environment specified"
            exit 1
          fi

      - name: Validate version
        run: |
          echo "Validating version: ${{ inputs.version }}"

      - name: Check secrets
        run: |
          if [[ -z "${{ secrets.API_KEY }}" ]]; then
            echo "Error: API_KEY secret is required"
            exit 1
          fi
          echo "All required secrets are available"

  deploy:
    name: 'Deploy Application'
    runs-on: ubuntu-latest
    needs: validate
    outputs:
      deployment-id: ${{ steps.deploy.outputs.deployment-id }}
      deployment-url: ${{ steps.deploy.outputs.deployment-url }}
      success: ${{ steps.deploy.outputs.success }}
    steps:
      - name: Setup deployment
        run: |
          echo "Setting up deployment for ${{ inputs.environment }}"
          echo "Version: ${{ inputs.version }}"
          echo "Parallel jobs: ${{ inputs.parallel-jobs }}"
          echo "Notifications enabled: ${{ inputs.enable-notifications }}"

      - name: Parse configuration
        run: |
          echo "Configuration: ${{ inputs.configuration }}"

      - name: Execute deployment
        id: deploy
        run: |
          deployment_id="reusable-deploy-$(date +%s)"
          deployment_url="https://${{ inputs.environment }}.example.com"

          echo "deployment-id=${deployment_id}" >> $GITHUB_OUTPUT
          echo "deployment-url=${deployment_url}" >> $GITHUB_OUTPUT
          echo "success=true" >> $GITHUB_OUTPUT

          echo "Deployment completed successfully"
          echo "ID: ${deployment_id}"
          echo "URL: ${deployment_url}"

  notify:
    name: 'Send Notifications'
    runs-on: ubuntu-latest
    needs: deploy
    if: ${{ inputs.enable-notifications }}
    steps:
      - name: Send Slack notification
        run: |
          echo "Sending Slack notification about deployment ${{ needs.deploy.outputs.deployment-id }}"

      - name: Create GitHub deployment
        run: |
          echo "Creating GitHub deployment status for ${{ needs.deploy.outputs.deployment-id }}"

show_heading ¤

Whether to show the heading in the documentation.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

heading ¤

A custom string to override the autogenerated heading of the object.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

A custom heading ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

heading_level ¤

The initial heading level to use.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash
Example action ¤
- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

show_branding ¤

Whether to show the action branding (logo and color) in the documentation.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

branding_icon ¤

Custom icon from https://feathericons.com/ to use for the branding.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

branding_icon_color ¤

Custom icon color for the feather icon.

Preview

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

Example action ¤

- uses: watermarkhu/mkdocstrings-github@v1
  with:
    input-string: ''

An example action.yaml file for the purpose of documentation

Inputs: ¤

Name Description Default
input-string

A string input parameter
input-number

A numeric input parameter

 42
input-boolean

A boolean input parameter

 false
Source of watermarkhu/mkdocstrings-github@v1 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
name: 'Example action'
description: 'An example `action.yaml` file for the purpose of documentation'
author: 'watermarkhu'

branding:
  icon: 'package'
  color: 'blue'

inputs:
  input-string:
    description: 'A string input parameter'
    required: true
  input-number:
    description: 'A numeric input parameter'
    required: false
    default: '42'
  input-boolean:
    description: 'A boolean input parameter'
    required: false
    default: 'false'

outputs:
  output-string:
    description: 'A string output from the action'
    value: 'result-value'
  output-number:
    description: 'A numeric output from the action'
    value: '123'

runs:
  using: 'composite'
  steps:
    - name: Execute action logic
      run: |
        echo "input-string=${{ inputs.input-string }}" >> $GITHUB_OUTPUT
        echo "output-number=123" >> $GITHUB_OUTPUT
        echo "output-json={\"key\": \"value\", \"number\": 456}" >> $GITHUB_OUTPUT
      shell: bash

show_toc_entry ¤

If the heading is not shown, at least add a ToC entry for it.

Preview

Table of contents
Some heading
Example object
Other heading

Table of contents
Some heading
Other heading

toc_label ¤

A custom string to override the autogenerated toc label of the root object.

Preview

Table of contents
Some heading
Example object
Other heading

Table of contents
Some heading
Custom label
Other heading