Update Markdown Action

A simple GitHub action to update sections in a markdown file.

Summary
Update markdown section
- Description
- Inputs
- Runs
- Usage
Complete Example
Development
Releasing
Testing
E2E Testing

Summary

Replaces the contents of a markdown (or, technically any file) between a pair of delimiters.

My repository

<!-- start-dynamic-section -->
<!-- end-dynamic-section -->

More test

Can become

 My repository

 <!-- start-dynamic-section -->
+<pre>
+# Something Dynamic
+
+Lorem ipsum dolor sit amet
+</pre>
 <!-- end-dynamic-section -->

 More test

Update markdown section

Description

Update a section in a markdown with arbitrary markup

Inputs

name	description	required	default
`file`	Relative path to markdown document to update	`false`	`README.md`
`delimiter_open`	Opening delimiter to indicate the section to update	`false`	`<!-- start-section -->`
`delimiter_close`	Closing delimiter to indicate the section to update	`false`	`<!-- end-section -->`
`content`	Contents to place inside the section delimiters	`true`	`""`

Runs

This action is a node20 action.

Usage

- uses: alistaircol/update-markdown-action@v0.2.0
  with:
    file:
    # Relative path to markdown document to update
    #
    # Required: false
    # Default: README.md

    delimiter_open:
    # Opening delimiter to indicate the section to update
    #
    # Required: false
    # Default: `<!-- start-section -->`

    delimiter_close:
    # Closing delimiter to indicate the section to update
    #
    # Required: false
    # Default: `<!-- end-section -->`

    content:
    # Contents to place inside the section delimiters
    #
    # Required: true
    # Default: ""

Complete Example

This workflow repository has an example workflow.

It updates the development section below with contents of task --list.

I have used this workflow elsewhere to:

List all tasks in a Taskfile with description
List all tasks being executed by an ansible playbook

Development

Project uses nvm.

nvm use
npm install

[!NOTE] This comment marks the start of a section which is updated using this action in an example workflow!

task: Available tasks for this project:
* actionlint:       Lint all workflow yaml files
* build:            Build action source for `dist`
* yamllint:         Lint all yaml files (and actionlint on workflow files)

[!NOTE] This comment marks the end of a section which is updated using this action!

Releasing

Once code has been updated, it must be built.

task build

ncc: Version 0.38.1
ncc: Compiling file index.js into CJS
  6kB  dist/licenses.txt
459kB  dist/index.js
465kB  [1037ms] - ncc 0.38.1

Get the most recent version that has been tagged and then increment the version.

git --no-pager tag --sort=refname

Update package.json's version attribute with the new version.

Tag and push to create a new version.

git tag --annotate --message "Update action to node 20" v0.2.0
git push --follow-tags

Testing

npm run test

E2E Testing

Testing the action locally for a sanity check.

cat <<EOF > e2e.md && \
  INPUT_FILE=e2e.md \
  INPUT_DELIMITER_OPEN='<!-- e2e-start-section -->' \
  INPUT_DELIMITER_CLOSE='<!-- e2e-end-section -->' \
  INPUT_CONTENT='Lorem ipsum dolor sit amet' \
  node dist/index.js \
  && less e2e.md \
  && rm e2e.md
<!-- e2e-start-section -->
<!-- e2e-end-section -->
EOF

You should see less open with:

<pre>
<!-- e2e-start-section -->
<!-- DO NOT EDIT THIS SECTION - IT IS UPDATED BY A GITHUB WORKFLOW -->
Lorem ipsum dolor sit amet
<!-- e2e-end-section -->
</pre>

alistaircol / update-markdown-action

readme