Integrating README.md and Makefile with makedown

What is makedown ?

makedown is a make command wrapper for Markdown files.

You can execute make targets written in *.md files by the make command.

overview.png

makedown - overview
  • You can write descriptions about make targets with texts, images, and even with tables, in markdown format.
  • It reads make targets written in Makefile.md or README.md by default.
  • You can integrate your README.md and Makefile into the same file.

How it works

  • makedown extracts make target definitions from the input Markdown file.
  • makedown reads Makefile.md or README.md implicitly, if it exists.
  • Then, it executes the given target by the make command.

Example

The following # sayhello: and # saygoodbye:, # variables: are examples of makedown.

# You can execute the `sayhello` target in the next section, like below:
$ makedown sayhello
Hello makedown!

sayhello:

@echo "Hello, $(WHO)!"

saygoodbye:

@echo "Bye for now," `date +%Y/%m/%d`

variables:

WHO = makedown

Usage

# This reads Makefile.md or README.md implicitly, then executes the given target.
$ makedown sayhello
Hello makedown!
# (-f) option is used to specifiy the input Markdown file explicitly.
$ makedown -f README.md sayhello
Hello makedown!
# This just generates 'Makefile'. No target will be executed.
$ makedown --out
# This generates the Makefile as 'MyMakefile', then executes the given target.
$ makedown --out MyMakefile sayhello
Hello makedown!
# This executes sayhello and saygoodbye by 'gmake' command.
$ makedown --make gmake sayhello saygoodbye
Hello makedown!
Bye for now, 2022/05/14
# The rest of arguments with double dash (--) will be passed to the 'make' command.
# ex.) The option (-w) is (print the current directory)
$ makedown -- -w sayhello
make: Entering directory ...
Hello makedown!
make: Leaving directory ...

Help

$ makedown -h
'makedown' is a 'make' command wrapper for Markdown files.
You can write 'make' targets in 'Makefile.md' or 'README.md', etc.
'makedown' executes 'make' targets written in *.md files by the 'make' command.
For more information,
https://github.com/hirokistring/makedown
Usage:
makedown [flags] [targets] ..
Examples:
$ cat README.md
# sayhello:
```
@echo Hello, $(WHO)!
```
# variables:
```
WHO = makedown
```
$ makedown sayhello
Hello, makedown!
Flags:
-h, --help help for makedown
--make string make command name in the PATH, like 'gmake'
-f, --markdown string input markdown file name
--out string output makefile name
--verbose prints verbose messages
-v, --version version for makedown

Other command line arguments will be passed to the make command at the run time. Threfore, you can use the almost all command line options of the make command.

How to install:

go install github.com/hirokistring/makedown

Or, download and extract the makedown executable file from the Releases page.

For more details

Read the DETAILS.md.

References

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store