Add configuration documentation enhancements (#770)

justin808 · web-flow · commit 3dfcfdb47389 · 2025-10-28T11:17:47.000-10:00
This PR completes the remaining TODOs from issue #711 by improving documentation discoverability and adding a quick-reference table for common configuration options. - **Enhanced README.md Configuration section** - Added bullet points highlighting key documentation topics including `assets_bundler_config_path` to help users quickly understand what's covered in the Configuration Guide - **Added Quick Reference table** to `docs/configuration.md` - Provides an at-a-glance view of the most commonly used configuration options with their types, defaults, and descriptions - **Updated Table of Contents** - Added link to the new Quick Reference section for easy navigation ## Motivation After PR #712 added comprehensive configuration documentation and improved error messages, these enhancements make it even easier for developers to: 1. Discover the Configuration Guide from the README 2. Quickly find configuration options without reading through detailed documentation 3. Understand at a glance what each option does and its default value Closes #711
diff --git a/README.md b/README.md
@@ -316,7 +316,15 @@ At its core, Shakapacker's essential function is to:
 
 ### Configuration and Code
 
-**📖 For a comprehensive guide to all configuration options, see [Configuration Guide](./docs/configuration.md)**
+**📖 For a comprehensive guide to all configuration options, see the [Configuration Guide](./docs/configuration.md)**
+
+This includes documentation for:
+
+- All `config/shakapacker.yml` options (including `assets_bundler_config_path`)
+- Environment-specific configuration
+- Development server settings
+- Build configurations (`config/shakapacker-builds.yml`)
+- Best practices and common patterns
 
 You will need your file system to correspond to the setup of your `config/shakapacker.yml` file.
 
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -4,6 +4,7 @@ This guide covers all configuration options available in `config/shakapacker.yml
 
 ## Table of Contents
 
+- [Quick Reference](#quick-reference)
 - [Basic Configuration](#basic-configuration)
 - [Source Configuration](#source-configuration)
 - [Output Configuration](#output-configuration)
@@ -16,6 +17,33 @@ This guide covers all configuration options available in `config/shakapacker.yml
 - [Environment-Specific Configuration](#environment-specific-configuration)
 - [Build Configurations (config/shakapacker-builds.yml)](#build-configurations-configshakapacker-buildsyml)
 
+## Quick Reference
+
+Common configuration options with their defaults:
+
+| Option                         | Type    | Default                                 | Description                                                |
+| ------------------------------ | ------- | --------------------------------------- | ---------------------------------------------------------- |
+| `assets_bundler`               | string  | `"webpack"`                             | Bundler to use: `"webpack"` or `"rspack"`                  |
+| `assets_bundler_config_path`   | string  | `"config/webpack"` or `"config/rspack"` | Directory containing bundler config files                  |
+| `javascript_transpiler`        | string  | `"swc"` or `"babel"`                    | Transpiler: `"swc"`, `"babel"`, or `"esbuild"`             |
+| `source_path`                  | string  | `"app/javascript"`                      | Root directory for JavaScript source files                 |
+| `source_entry_path`            | string  | `"packs"`                               | Subdirectory within `source_path` for entry points         |
+| `nested_entries`               | boolean | `true`                                  | Discover entry points in subdirectories                    |
+| `public_output_path`           | string  | `"packs"`                               | Subdirectory within `public_root_path` for compiled assets |
+| `private_output_path`          | string  | `nil`                                   | Directory for private server-side bundles (e.g., SSR)      |
+| `compile`                      | boolean | env-specific                            | Compile assets on-demand when requests are made            |
+| `cache_manifest`               | boolean | `false` (dev), `true` (prod)            | Cache manifest.json in memory                              |
+| `compiler_strategy`            | string  | `"mtime"` (dev), `"digest"` (prod)      | How to determine if recompilation is needed                |
+| `useContentHash`               | boolean | `false` (dev), `true` (prod)            | Include content hashes in asset filenames                  |
+| `webpack_compile_output`       | boolean | `true`                                  | Show webpack/rspack compilation output                     |
+| `shakapacker_precompile`       | boolean | `true`                                  | Include in `rails assets:precompile`                       |
+| `ensure_consistent_versioning` | boolean | `true`                                  | Enforce gem/npm version matching                           |
+| `dev_server.host`              | string  | `"localhost"`                           | Development server host                                    |
+| `dev_server.port`              | number  | `3035`                                  | Development server port                                    |
+| `dev_server.hmr`               | boolean | `false`                                 | Enable Hot Module Replacement                              |
+
+For detailed explanations, examples, and additional options, see the sections below.
+
 ## Basic Configuration
 
 ### `assets_bundler`
