SwarmLab-HowTos/labs/Howtos/asciidoc/_includes/process-multi.adoc

////
Included in:

- user-manual: Process multiple source files from the CLI
////

You can pass multiple source files or a filename pattern to the Asciidoctor CLI and it will convert each file given in turn.

Let's assume there exist two AsciiDoc files in the current directory, [.path]_a.adoc_ and [.path]_b.adoc_.
You can pass both files to Asciidoctor using a single command, as follows:

 $ asciidoctor a.adoc b.adoc

Asciidoctor will convert both files, transforming [.path]_a.adoc_ to [.path]_a.html_ and [.path]_b.adoc_ to [.path]_b.html_.

To save some typing, you can use the glob operator (`+*+`) to match all AsciiDoc files in the current directory using a single argument:

 $ asciidoctor *.adoc

Your shell will automatically expand the pattern and interpret the command exactly as you had typed it above:

 $ asciidoctor a.adoc b.adoc

You can pass all AsciiDoc files inside direct subfolders using the glob operator (`+*+`) in place of the directory name:

 $ asciidoctor */*.adoc

To match all files in the current directory and direct subfolders, combine both glob patterns:

 $ asciidoctor *.adoc */*.adoc

Since the globs in this command rely on shell expansion, the command is not portable across platforms.
To make it portable, you can allow the Asciidoctor CLI to expand the globs.
To do so, instruct the shell to not expand the glob by quoting the pattern, as shown here:

 $ asciidoctor '*.adoc' '*/*.adoc'

This time, the arguments `+*.adoc+` and `+*/*.adoc+` are passed directly to Asciidoctor instead of being expanded.
Asciidoctor handles the glob matching in a manner that is portable across platforms.

CAUTION: If you process multiple nested AsciiDoc files at once and are also applying a custom stylesheet to them, you'll need to <<user-manual#style-nest-doc,manage the stylesheet's location>>.

But it gets better.
The glob handling in Asciidoctor (which matches the rules of file globbing in Ruby) is likely more powerful than what your shell offers.
For example, you can match AsciiDoc files in the current folder and in folders of any depth using the double glob operator (`+**+`).

 $ asciidoctor '**/*.adoc'

Most shells do not honor the double glob pattern.
Thus, to ensure both portability and flexibility when specifying a glob pattern, always enclose the argument in quotes.

If you specify an output folder, the source folders are not preserved by default.
To preserve the folders, specify which portion of the path to remove using the `-R` flag:

 $ asciidoctor -D out -R src 'src/**/*.adoc'

In this case, the folder structure under the `src` folder will be replicated.

You can use the special value `.` to indicate you want the folder structure of the source and output to be mirrored exactly.
For example:

 $ asciidoctor -D out -R . '**/*.adoc'

If you find yourself pushing the boundaries of what can be achieved using the CLI to convert multiple AsciiDoc files (including processing resources like images), consider switching to a build tool like Maven or Gradle.
Both tools provide excellent Asciidoctor integration.
Refer to the <<asciidoctor-maven-plugin.adoc#,Asciidoctor Maven plugin>> or <<asciidoctor-gradle-plugin.adoc#,Asciidoctor Gradle plugin>> for details.