[book]
authors = ["Patrick Elsen"]
language = "en"
multilingual = false
src = "src"
title = "mdbook-files book"

[preprocessor.files]
command = "cargo run --"
prefix = ".."

[output.html]
additional-css = ["style.css"]

# Summary

- [Getting Started](getting-started.md)
    - [Install](getting-started/install.md)
    - [Setup](getting-started/setup.md)
    - [Usage](getting-started/usage.md)
- [Reference](reference.md)
    - [Plugin](reference/plugin.md)
    - [Files](reference/files.md)
- [Examples](examples.md)
- [Tests](tests.md)
    - [Plugin Source](tests/plugin.md)
    - [Book Source](tests/book.md)

# Examples

# Install

To install `mdbook-files`, you have two options. The easiest installation path is
to download a prebuilt binary from the GitHub releases. If you have Cargo installed,
you can also build it from source.

### Prebuilt

You can go to the [Releases](https://github.com/xfbs/mdbook-files/releases) page and download
whichever prebuilt binary is appropriate for the operating system that you are using.

For example, to install it in Linux, you can do like this. You will need to set
the `MDBOOK_FILES_VERSION` to the latest version (or whichever version you want to
install).

```bash
export MDBOOK_FILES_VERSION=0.1.0
curl -sSL "https://github.com/xfbs/mdbook-files/releases/download/v$MDBOOK_FILES_VERSION/mdbook-files-v$MDBOOK_FILES_VERSION-x86_64-unknown-linux-musl.tar.gz" | sudo tar -C /usr/local/bin -xzv
```

### From Source

Another approach is to install `mdbook-files` from source. This approach works on operating
systems for which no builds exist. To do so, you need to have Cargo[^1] installed.

    cargo install mdbook-files --version 0.1.0

## Verify

Once you have installed it, you should be able to verify that you have installed it correctly
by running this command:

    mdbook-files --version

Which should respond with whichever version you have installed.

[^1]: Use [rustup](https://rustup.rs/) to install it, if neccessary.

# Setup

To get started with `mdbook-files`, the next step is to add it to your `mdbook`
configuration.  To do this, you have two options: the automatic install method,
and the manual installation method. The former method is recommended, but the
latter is still documented here in case you run into issues.

### Automatic setup

To install `mdbook-files` automatically, given that you have already installed it,
you can run this command:

    mdbook-files install

This will run perform the same steps as the manual installation method.

### Manual setup

Next, setup your project by adding this to the configuration:

```toml
[preprocessor.files]
prefix = "."

[output.html]
additional-css = ["style.css"]
```

Next, you need to add the `style.css` file into your project, by copying it
from the repository.

## Verify

Once you have done this, you should be able to run `mdbook` to build your book
and not get any issues.

    mdbook build

If this succeeds, you are ready for the next step.

# Usage

To use `mdbook-files`, simply drop something like this into your project's
markdown source:

~~~markdown
```files
path = "path/to/folder"
```
~~~

This will create a widget which renders all of the files in `path/to/files`.

# Getting Started

Preprocessor for [mdBook][mdBook] which renders files from a directory as an
interactive widget, with syntax highlighting.

![Example of mdbook-files](example.png)

I wrote this to make it easy to showcase examples inside books written using
mdBook, which have more than just one file, such as entire Rust crates. The
file picker makes it easy to browse around, and the syntax highlighting works
just as simple code examples would work.

[mdBook]: https://github.com/rust-lang/mdBook

# Files

To render files, a pseudo-code block needs to be added to your markdown source
that looks like this:

~~~markdown
```files
path = "path/to/folder"
# other config
```
~~~

The `mkdbook-files` plugin will pick up on these and replace them with file widgets.

This section explains the options available for every files instance.

```toml
# path to folder to select files to show
path = "path/to/folder"

# Override list for files. Files added here are included even if they are ignored,
# prefixing entries with an exclamation mark turns them into ignores.
files = ["*.png", "!*.md"]

# When set, is the default file to show.
default_file = "README.md"

# Process ignores case insensitively
ignore_case_insensitive = false

# Do not cross file system boundaries.
#
# When this option is enabled, directory traversal will not descend into directories that are
# on a different file system from the root path.
same_file_system = false

# Select the file type given by name.
types = ["png", "rust"]

# Enables ignoring hidden files.
hidden = false

# Whether to follow symbolic links or not.
follow_links = false

# Enables reading `.ignore` files.
#
# `.ignore` files have the same semantics as gitignore files and are supported by search
# tools such as ripgrep and The Silver Searcher.
dot_ignore = false

# Enables reading a global `gitignore` file, whose path is specified in git’s `core.excludesFile`
# config option.
git_global = false

# Enables reading `.git/info/exclude` files.
git_exclude = false

# Enables reading `.gitignore` files.
git_ignore = false

# Whether a git repository is required to apply git-related ignore rules (global rules,
# .gitignore and local exclude rules).
require_git = false

# Enables reading ignore files from parent directories.
git_ignore_parents = false

# Maximum depth to recurse.
#max_depth = 1234

# Ignore files above the specified limit.
#max_filesize = 10000
```

# Plugin

The plugin configuration is the settings which are in the `book.toml` file.

These are all of the options, along with their semantics and default values:

```toml
[preprocessor.files]

# specify name of or path to the binary
command = "mdbook-files"

# path prefix added to all invocations
prefix = "."
```

# Reference

This section explains all of the options for configurting `mdbook-files` and
all of the options for the instantiation.

# Subchapter

This is a subchapter.

```files
path = "docs"
files = ["!**/*.png"]
hidden = true
git_ignore = true
default_file = "src/SUMMARY.md"
```

## Subchapter

# Plugin Source

Source code of `mdbook-files`:

```files
path = "."
files = ["!.github", "!*.png", "!docs"]
hidden = true
git_ignore = true
```

This is some paragraph after the thing.

# Source

Source code of `mdbook-files`:

```files
path = "."
files = ["!.github", "!*.png", "!docs"]
hidden = true
git_ignore = true
```

This is some paragraph after the thing.