Make compression-zstd opt-in and add documentation

Changes:
- Remove compression-zstd from default features (requires C bindings)
- Add comprehensive documentation for zstd compression feature
- Document compression functions and config methods
- Reorganize README features section for clarity

The zstd feature is now opt-in due to its C library dependency,
which may not be compatible with all build environments.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: SeriousBug

Cargo.toml

@@ -23,7 +23,7 @@ zstd = "0.13"
 actix-web = "4.4"
 
 [features]
-default = ["interpolate-folder-path", "include-exclude", "compression-zstd"]
+default = ["interpolate-folder-path", "include-exclude"]
 # Even in debug mode use a release embed.
 # We use this to test embed code in our tests.
 always-embed = ["rust-embed-for-web-impl/always-embed"]

README.md

@@ -76,9 +76,11 @@ archives already don't include their compressed versions. However you can
 
 ## Features
 
-Both of the following features are enabled by default.
+### Default Features
 
-### `interpolate-folder-path`
+The following features are enabled by default.
+
+#### `interpolate-folder-path`
 
 Allow environment variables and `~`s to be used in the `folder` path. Example:
 
@@ -91,7 +93,7 @@ struct Asset;
 `~` will expand into your home folder, and `${PROJECT_NAME}` will expand into
 the value of the `PROJECT_NAME` environment variable.
 
-### `include-exclude`
+#### `include-exclude`
 
 You can filter which files are embedded by adding one or more `#[include = "*.txt"]` and `#[exclude = "*.jpg"]` attributes.
 Matching is done on relative file paths --the paths you use for the `.get` call-- via [`globset`](https://docs.rs/globset/latest/globset/).
@@ -111,7 +113,26 @@ For example, if you wanted to exclude all `.svg` files except for one named
 struct Assets;
 ```
 
-### `prefix`
+### Optional Features
+
+#### `compression-zstd`
+
+Enables zstd compression support for embedded files. When enabled, files will be compressed with zstd (in addition to gzip and brotli), allowing you to serve zstd-compressed content to clients that support it.
+
+**Note:** This feature is **not enabled by default** because the `zstd` crate uses C bindings, which may not be compatible with all build environments.
+
+To enable zstd compression, add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+rust-embed-for-web = { version = "11.2.1", features = ["compression-zstd"] }
+```
+
+You can also disable zstd compression for specific embeds using the `#[zstd = false]` attribute as described in the "Disabling compression" section above.
+
+### Other Configuration
+
+#### `prefix`
 
 You can specify a prefix, which will be added to the path of the files. For example:
 

impl/src/compress.rs

@@ -42,9 +42,14 @@ pub(crate) fn compress_br(data: &[u8]) -> Option<Vec<u8>> {
     }
 }
 
+/// Compresses data using zstd compression.
+///
+/// Returns the compressed data if it's smaller than the threshold, `None` otherwise.
+/// Uses compression level 3 as a balance between compression ratio and speed.
 #[cfg(feature = "compression-zstd")]
 pub(crate) fn compress_zstd(data: &[u8]) -> Option<Vec<u8>> {
     let mut data_zstd: Vec<u8> = Vec::new();
+    // Level 3 provides good compression with reasonable speed for build-time compression
     let mut encoder = ZstdEncoder::new(&mut data_zstd, 3).expect("Failed to create zstd encoder");
     encoder
         .write_all(data)

utils/src/config.rs

@@ -61,6 +61,7 @@ impl Config {
         self.br = status;
     }
 
+    /// Enable or disable zstd compression for embedded files.
     pub fn set_zstd(&mut self, status: bool) {
         self.zstd = status;
     }
@@ -109,6 +110,10 @@ impl Config {
         self.br
     }
 
+    /// Check if zstd compression should be used for embedded files.
+    ///
+    /// Returns `false` when the compression-zstd feature is not enabled,
+    /// even if the config value is set to `true`.
     pub fn should_zstd(&self) -> bool {
         #[cfg(feature = "compression-zstd")]
         {