From 216fb9af3dcbee29152c1ae2e0a9c05e05363e54 Mon Sep 17 00:00:00 2001
From: "Daniel G. Taylor" <danielgtaylor@gmail.com>
Date: Wed, 20 Dec 2023 22:48:26 -0800
Subject: [PATCH] docs: improved docs; auto light/dark mode

---
 docs/docs/features/cli.md | 36 ++++++++++++++++++++++++++++++++++--
 docs/mkdocs.yml           | 13 ++++++++++++-
 2 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/docs/docs/features/cli.md b/docs/docs/features/cli.md
index 595fa496..86cc317c 100644
--- a/docs/docs/features/cli.md
+++ b/docs/docs/features/cli.md
@@ -30,11 +30,16 @@ func main() {
 }
 ```
 
-You can then run the CLI with and see the results:
+You can then run the CLI and see the results:
 
 ```sh title="Terminal"
+// Run with defaults
 $ go run main.go
 I was run with debug:false host: port:8888
+
+// Run with options
+$ go run main.go --debug=true --host=localhost --port=8000
+I was run with debug:true host:localhost port:8000
 ```
 
 To do useful work, you will want to register a handler for the default start command and optionally a way to gracefully shutdown the server:
@@ -68,6 +73,25 @@ cli := huma.NewCLI(func(hooks huma.Hooks, opts *Options) {
 
     Option fields are automatically converted to `--kebab-casing` for use on the command line. If you want to use a different name, use the `name` struct tag to override the default behavior!
 
+## Passing Options
+
+Options can be passed explicitly as command-line arguments to the service or they can be provided by environment variables prefixed with `SERVICE_`. For example, to run the service on port 8000:
+
+```bash
+# Example passing command-line args
+$ go run main.go --port=8000
+
+# Short arguments are also supported
+$ go run main.go -p 8000
+
+# Example passing by environment variables
+$ SERVICE_PORT=8000 go run main.go
+```
+
+!!! warning "Precedence"
+
+    If both environment variable and command-line arguments are present, then command-line arguments take priority.
+
 ## Custom Options
 
 Custom options are defined by adding to your options struct. The following types are supported:
@@ -116,7 +140,15 @@ cli.Root().AddCommand(&cobra.Command{
 })
 ```
 
-Now you can run your service and use the new command: `go run . openapi`.
+Now you can run your service and use the new command: `go run . openapi`. Notice that it never starts the server; it just runs your command handler code. Some ideas for custom commands:
+
+-   Print the OpenAPI spec
+-   Print JSON Schemas
+-   Run database migrations
+-   Run customer scenario tests
+-   Bundle common actions into a single utility command, like adding a new user
+
+### Custom Commands with Options
 
 If you want to access your custom options struct with custom commands, use the [`huma.WithOptions(func(cmd *cobra.Command, args []string, options *YourOptions)) func(cmd *cobra.Command, args []string)`](https://pkg.go.dev/github.com/danielgtaylor/huma/v2#WithOptions) utitity function. It ensures the options are parsed and available before running your command.
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index a2b1e931..21f8ec01 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -62,14 +62,22 @@ theme:
   logo: logo.png
   favicon: favicon.png
   palette:
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+      primary: blue
+      accent: custom
+
     # Palette toggle for light mode
     - media: "(prefers-color-scheme: light)"
-      scheme: default
       toggle:
         icon: material/brightness-7
         name: Switch to dark mode
       primary: blue
       accent: custom
+
     # Palette toggle for dark mode
     - media: "(prefers-color-scheme: dark)"
       scheme: slate
@@ -99,6 +107,9 @@ extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/danielgtaylor/huma
+  analytics:
+    provider: google
+    property: G-YCZGGQHTX1
 extra_css:
   - stylesheets/asciinema-player.css
   - stylesheets/extra.css