• example-into-readme
  • Overview
    • Before running
    • After running
  • Usage examples
    • Include a file
    • Include command output
    • Include another markdown file
    • Specify the language for code blocks
    • Quoting the output of commands
    • Outline generator
    • Include other markdown files
    • Include command output
  • Install
    • Use go install
    • Use the scoop-installer

example-into-readme automatically inserts example files or command outputs into your README.md. It helps you keep your documentation up-to-date — without manually copying and pasting code or results.

This tool is meant to be used locally as a CLI helper, not as a GitHub Action.

```go.mod
```

```go.mod
module github.com/hymkor/example-into-readme

go 1.20

require golang.org/x/text v0.8.0
```

The program finds code blocks whose info-string contains a filename, then replaces the block’s content with the actual file content.

$ example-into-readme
Convert from README.md to README.tmp
Include go.mod
Rename README.md to README.md~
Rename README.tmp to README.md

When the filename ends with *.go, it skips lines before package to ignore //go:build directives.

```go.mod
```

→ replaced with the actual contents of go.mod.

```go run example.go |
```

→ replaced with the result of running the command.

<!-- example.md -->
<!-- -->

→ replaced with the contents of example.md.

Some file extensions are not automatically recognized by GitHub’s syntax highlighting. You can specify the language name explicitly before the filename:

```rust foo.rs
```

To embed command results, write the command followed by a |:

```COMMANDNAME ARGS ... |
```

You can insert a markdown outline between these markers:

<!-- outline -->
<!-- -->

<!-- filename.md -->
<!-- -->

<!-- COMMANDNAME ARGS ... | -->
<!-- -->

Download the binary from Releases and extract the executable.

go install github.com/hymkor/example-into-readme@latest

scoop install https://raw.githubusercontent.com/hymkor/example-into-readme/master/example-into-readme.json

or

scoop bucket add hymkor https://github.com/hymkor/scoop-bucket
scoop install example-into-readme