/markdown-extract

Extract sections of a markdown file. Useful for automatically extracting changelogs

Primary LanguageRustMIT LicenseMIT

Markdown Extract

Crates.io Docker Pulls Build & Test

Extract sections of a markdown file with a regular expression! Great for changelogs ;)

Usage

Given a document called my-document.md:

# Welcome

This is my amazing markdown document.

## Extract me!

This section should be pulled out.

You can extract the second section with the following command:

$ markdown-extract "Extract me!" my-document.md
## Extract me!

This section should be pulled out.

Installation

If you've got Rust installed on your system, you can simply install markdown-extract with Cargo.

$ cargo install markdown-extract

Docker

A Docker image is also available, and can be installed with the following command:

$ docker pull sean0x42/markdown-extract:v2

You can then run the container with the following command:

$ docker run -it sean0x42/markdown-extract:v2 --help

Note that because markdown-extract accesses the file system, you will need to mount a volume if you want to access a file on the host. e.g.

$ docker run -v $PWD:/opt -it sean0x42/markdown-extract:v2 v2.0.0 /opt/CHANGELOG.md

If you know a better way of achieving this, please let me know!

Github Action

This project can be used as a Github action.

Here is a sample workflow usage:

- id: extract-changelog
  uses: sean0x42/markdown-extract@v2
  with:
   file: CHANGELOG.md
   pattern: 'v2.0.0'
- name: Write output to file
  run: |
    printf '${{ steps.extract-changelog.outputs.markdown }}' > CHANGELOG-extracted.txt
- uses: actions/upload-artifact@v3
  with:
   name: changelog
   path: CHANGELOG-extracted.txt

For a complete reference view the action.yml.

The action version corresponds to the version of the tool.

Use Cases

There aren't many, to be honest.

  1. Extract patch notes from a CHANGELOG.md by version.
  2. The talented folks at HashiCorp are using markdown-extract to extract API documentation, and inject it into OpenAPI schemas.

If you have another use for this tool, please let me know!