FILES.md

File Generation

Markout can run in one of two modes

1. Apply Mode
2. Expect Mode

Apply Mode

Apply is the default mode. It generates files and directories and deletes previously generated files and directories that were not regenerated.

Files and Directories

Markout provides a straightforward DSL for generating files and directories

markout(Path("..")) {
    directory("my-directory") {
        directory("inner") {
            file("inner.txt", "another plain text file")
        }

        file("plain.txt", "the contents of a plain text file")

        file("circle.svg", """
            <svg height="100" width="100">
                <circle cx="50" cy="50" r="40" fill="black" />
            </svg> 
        """.trimIndent())
    }

    markdown("readme") {
        -"A markdown file"
        -"The .md extension is automatically added to the filename if it is not present"
    }
}

When this code is run it generates the following file tree

my-directory
├─ inner
│  └─ inner.txt
├─ circle.svg
└─ plain.txt
readme.md

File Tracking

When Markout generates directories it includes a .markout file. This is how Markout keeps track of generated files. It should always be checked into git. Markout will never change or delete an existing file or directory unless it is tracked in .markout

File tracking allows regular files to be mixed in with generated ones. For example, you might mix handwritten markdown into your docs directory.

Expect Mode

Running Markout in expect mode will cause it to fail when it encounters changes. This allows you to check that files have been generated and are consistent with the code. It is intended for use in CI workflows.

To use Expect mode, run markout with the MARKOUT_MODE environment variable set to expect.

MARKOUT_MODE=expect ./gradlew :readme:run