Expands docs

.github/workflows/book.yml

@@ -0,0 +1,37 @@
+name: Book
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: Book
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Setup mdbook
+        uses: peaceiris/actions-mdbook@v1.2.0
+      - run: cd docs && mdbook build
+      - name: Upload artifacts
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: 'docs/book'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -6,7 +6,7 @@
 Preprocessor for [mdBook][mdBook] which renders files from a directory as an
 interactive widget, with syntax highlighting.
 
-![Example of mdbook-files](example.png)
+![Example of mdbook-files](docs/src/example.png)
 
 ## Example
 

docs/src/SUMMARY.md

@@ -1,6 +1,13 @@
 # Summary
 
-- [Setup](setup.md)
+- [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)

docs/src/examples.md

@@ -0,0 +1 @@
+# Examples

docs/src/getting-started.md

@@ -0,0 +1,13 @@
+# 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

docs/src/getting-started/install.md

@@ -0,0 +1,37 @@
+# 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.

docs/src/getting-started/setup.md

@@ -0,0 +1,39 @@
+# 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.

docs/src/getting-started/usage.md

@@ -0,0 +1,12 @@
+# 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`.

docs/src/reference.md

@@ -0,0 +1,4 @@
+# Reference
+
+This section explains all of the options for configurting `mdbook-files` and
+all of the options for the instantiation.

docs/src/reference/files.md

@@ -0,0 +1,74 @@
+# 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"
+
+# Add a glob to the set of overrides.
+#
+# Globs provided here have precisely the same semantics as a single line in a gitignore file,
+# where the meaning of `!` is inverted: namely, `!` at the beginning of a glob will ignore a
+# file. Without `!`, all matches of the glob provided are treated as whitelist matches.
+ignore = ["*.png", "!*.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
+```

docs/src/reference/plugin.md

@@ -0,0 +1,15 @@
+# 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 = "."
+```

docs/src/tests/book.md

@@ -6,6 +6,7 @@ This is a subchapter.
 path = "docs"
 hidden = true
 git_ignore = true
+ignore = ["!**/*.png"]
 ```
 
 ## Subchapter

src/main.rs

@@ -23,6 +23,7 @@ impl Options {
                 serde_json::to_writer(io::stdout(), &output)?;
                 Ok(())
             }
+            Some(Command::Install(_command)) => Ok(()),
         }
     }
 }

src/options.rs

@@ -1,18 +1,32 @@
 use clap::Parser;
+use std::path::PathBuf;
 
+/// Preprocessor for mdBook which renders files from a directory as an interactive widget, with
+/// syntax highlighting.
 #[derive(Parser, Debug)]
+#[command(author, version, about)]
 pub struct Options {
     #[clap(subcommand)]
     pub command: Option<Command>,
 }
 
 #[derive(Parser, Debug)]
 pub enum Command {
+    /// Check if the renderer is supported.
     Supports(SupportsCommand),
+    /// Process a parsed book (default).
     Process,
+    /// Install support for mdbook-files into the current mdbook project.
+    Install(InstallCommand),
 }
 
 #[derive(Parser, Debug)]
 pub struct SupportsCommand {
     pub renderer: String,
 }
+
+#[derive(Parser, Debug)]
+pub struct InstallCommand {
+    #[clap(long)]
+    pub assets: Option<PathBuf>,
+}