diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml new file mode 100644 index 0000000..f8e39e2 --- /dev/null +++ b/.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 diff --git a/README.md b/README.md index dfa9a08..8ba22c7 100644 --- a/README.md +++ b/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 diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index f11ec8e..129f470 100644 --- a/docs/src/SUMMARY.md +++ b/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) diff --git a/docs/src/example.png b/docs/src/example.png new file mode 100644 index 0000000..2c94ec1 Binary files /dev/null and b/docs/src/example.png differ diff --git a/docs/src/examples.md b/docs/src/examples.md new file mode 100644 index 0000000..df635b4 --- /dev/null +++ b/docs/src/examples.md @@ -0,0 +1 @@ +# Examples diff --git a/docs/src/getting-started.md b/docs/src/getting-started.md new file mode 100644 index 0000000..c5a7db9 --- /dev/null +++ b/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 diff --git a/docs/src/getting-started/install.md b/docs/src/getting-started/install.md new file mode 100644 index 0000000..ce24d53 --- /dev/null +++ b/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. diff --git a/docs/src/getting-started/setup.md b/docs/src/getting-started/setup.md new file mode 100644 index 0000000..c1bb3ce --- /dev/null +++ b/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. diff --git a/docs/src/getting-started/usage.md b/docs/src/getting-started/usage.md new file mode 100644 index 0000000..7d7eaf4 --- /dev/null +++ b/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`. diff --git a/docs/src/reference.md b/docs/src/reference.md new file mode 100644 index 0000000..21f7b0b --- /dev/null +++ b/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. diff --git a/docs/src/reference/files.md b/docs/src/reference/files.md new file mode 100644 index 0000000..ee1e0cf --- /dev/null +++ b/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 +``` diff --git a/docs/src/reference/plugin.md b/docs/src/reference/plugin.md new file mode 100644 index 0000000..7473f93 --- /dev/null +++ b/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 = "." +``` diff --git a/docs/src/setup.md b/docs/src/setup.md deleted file mode 100644 index ab2fa6b..0000000 --- a/docs/src/setup.md +++ /dev/null @@ -1,12 +0,0 @@ -# Setup - -Install `mdbook-files`: - - cargo install mdbook-files - -Next, setup your project by adding this to the configuration: - -```toml -[preprocessor.files] -prefix = "examples" -``` diff --git a/docs/src/tests/book.md b/docs/src/tests/book.md index c649794..cba5ed4 100644 --- a/docs/src/tests/book.md +++ b/docs/src/tests/book.md @@ -6,6 +6,7 @@ This is a subchapter. path = "docs" hidden = true git_ignore = true +ignore = ["!**/*.png"] ``` ## Subchapter diff --git a/src/main.rs b/src/main.rs index eb20362..20e0bb4 100644 --- a/src/main.rs +++ b/src/main.rs @@ -23,6 +23,7 @@ impl Options { serde_json::to_writer(io::stdout(), &output)?; Ok(()) } + Some(Command::Install(_command)) => Ok(()), } } } diff --git a/src/options.rs b/src/options.rs index c78b2ad..9929556 100644 --- a/src/options.rs +++ b/src/options.rs @@ -1,6 +1,10 @@ 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, @@ -8,11 +12,21 @@ pub struct Options { #[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, +}