Customizing README Templates with the Centralized Workflow

[ocots]

User Guide: Customizing README Templates with the Centralized Workflow

This guide explains how to customize your repository’s README.template.md and automatically generate the final README.md using the centralized update workflow.

1. Using the Template Includes

The workflow supports several include placeholders in README.template.md. These placeholders are replaced with the content from centralized markdown files:

Placeholder	Description
<!-- INCLUDE_ABOUT -->	Inserts content from ABOUT.md. This usually describes the package/application.
<!-- INCLUDE_INSTALL -->	Inserts content from INSTALL.md. This usually provides installation instructions.
<!-- INCLUDE_CONTRIBUTING -->	Inserts content from CONTRIBUTING.md. This usually contains contribution guidelines.
<!-- INCLUDE_BADGES: ... -->	Inserts a table of badges. You must list the categories you want, separated by commas.

Example:

# MyPackage.jl

<!-- INCLUDE_BADGES: Documentation, CI, Coverage, PackageEvaluation, Release, Citation, License, CodeStyle, Downloads -->

<!-- INCLUDE_ABOUT -->

<!-- INCLUDE_INSTALL -->

<!-- INCLUDE_CONTRIBUTING -->

2. Badge Categories

The workflow supports the following badge categories:

Category	Description
Documentation	Inserts links to stable and dev docs.
CI	Continuous integration / build status badge.
Coverage	Test coverage badge (via Codecov).
PackageEvaluation	Julia package evaluation badges, including dependencies.
Release	Latest release version badge.
Citation	Optional DOI / Zenodo badge. Must be provided via workflow input.
License	License badge.
CodeStyle	Code style badges (BlueStyle, Aqua.jl).
Downloads	Julia package download statistics.

Note: For the Citation badge, you must provide a Markdown badge string in the workflow input citation_badge. Example:

[![DOI](https://zenodo.org/badge/541187171.svg)](https://zenodo.org/doi/10.5281/zenodo.16753152)

3. Setting Up the Workflow

To automatically generate the README, you need to create a workflow in your repository. Example workflow:

name: Update README with ABOUT.md and INSTALL.md

on:
  schedule:
    - cron: '0 6 * * 1'   # every Monday at 06:00 UTC
  workflow_dispatch:       # manual trigger

jobs:
  check-template:
    runs-on: ubuntu-latest
    outputs:
      has_template: ${{ steps.check.outputs.has_template }}
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

      - name: Check for README.template.md
        id: check
        shell: bash
        run: |
          if [[ -f "README.template.md" ]]; then
            echo "has_template=true" >> "$GITHUB_OUTPUT"
          else
            echo "has_template=false" >> "$GITHUB_OUTPUT"
            echo "README.template.md not found. Skipping README update." >&2
          fi

  call-shared:
    needs: check-template
    if: ${{ needs.check-template.outputs.has_template == 'true' }}
    uses: control-toolbox/CTActions/.github/workflows/update-readme.yml@main
    with:
      template_file: README.template.md
      output_file: README.md
      package_name: MyPackage        # package for INSTALL.md
      repo_name: organization/MyPackage.jl        # repository for CONTRIBUTING.md links
      doc_url: https://organization.github.io/MyPackage.jl        # url of the documentation
      citation_badge: "[![DOI](https://zenodo.org/badge/541187171.svg)](https://zenodo.org/doi/10.5281/zenodo.16753152)" # example, can be empty
      assignee: "ocots"
    secrets: inherit

Inputs to Update:

• template_file: path to your README template (usually README.template.md).
• output_file: path for the generated README (usually README.md).
• package_name: Julia package name for INSTALL.md.
• repo_name: Repository full name (with GitHub organization) for CONTRIBUTING.md links.
• doc_url: url of the documentation
• citation_badge (optional): Markdown string for DOI / Zenodo badge.
• assignee (optional): GitHub username to assign the PR to. Leave empty if you do not want to assign anyone.

Notes:

• The workflow will create a Pull Request with the updated README automatically.
• If assignee is provided, the PR will be assigned to that user. Otherwise, no one will be assigned.
• The workflow fetches the latest centralized ABOUT.md, INSTALL.md, and CONTRIBUTING.md files from the control-toolbox/.github repository.

4. Summary

1. Customize README.template.md using the placeholders.
2. Decide which badge categories to include.
3. Create a workflow YAML in your repository that calls the centralized workflow, optionally providing a citation badge and assignee.
4. Commit and push. The workflow will generate a README and create a PR.