Add support for appendices: landscape diagrams, tables, and images; implement Kroki URL configurability; enhance directive parsing logic.

diagram.go

@@ -10,15 +10,22 @@ import (
 	"net/http"
 	"os"
 	"path/filepath"
+	"time"
 )
 
+// krokiBaseURL is the Kroki instance to use. Override with the -kroki flag.
+// Self-host: docker run -d -p 8000:8000 yuzutech/kroki
+var krokiBaseURL = "https://kroki.io"
+
+// krokiClient is a shared HTTP client with a short timeout so a dead Kroki
+// backend fails fast instead of hanging for ~60 s per diagram.
+var krokiClient = &http.Client{Timeout: 10 * time.Second}
+
 // RenderDiagramViaKroki converts a diagram source (Mermaid, PlantUML, etc.)
-// to a PNG image using the Kroki.io public rendering service and caches the
-// result in the OS temp directory.
-//
-// The cache key is the SHA-256 hash of the diagram source, so unchanged
-// diagrams are not re-fetched between runs.
+// to a PNG image via a Kroki rendering service and caches the result in the
+// OS temp directory. The base URL is controlled by krokiBaseURL (-kroki flag).
 //
+// Cache key: SHA-256 of the diagram source — unchanged diagrams are not re-fetched.
 // Supported languages: "mermaid", "plantuml" / "puml"
 func RenderDiagramViaKroki(lang, code string) (string, error) {
 	if lang == "puml" {
@@ -35,7 +42,7 @@ func RenderDiagramViaKroki(lang, code string) (string, error) {
 		return "", fmt.Errorf("zlib close: %w", err)
 	}
 	encoded := base64.URLEncoding.EncodeToString(buf.Bytes())
-	url := fmt.Sprintf("https://kroki.io/%s/png/%s", lang, encoded)
+	url := fmt.Sprintf("%s/%s/png/%s", krokiBaseURL, lang, encoded)
 
 	// Deterministic cache path based on content hash
 	hash := fmt.Sprintf("%x", sha256.Sum256([]byte(code)))
@@ -45,14 +52,14 @@ func RenderDiagramViaKroki(lang, code string) (string, error) {
 		return cachePath, nil // cache hit
 	}
 
-	resp, err := http.Get(url) //nolint:gosec // URL is constructed from user content, acceptable here
+	resp, err := krokiClient.Get(url) //nolint:gosec
 	if err != nil {
-		return "", fmt.Errorf("kroki request: %w", err)
+		return "", fmt.Errorf("kroki request failed (is %s reachable?): %w", krokiBaseURL, err)
 	}
 	defer resp.Body.Close()
 
 	if resp.StatusCode != http.StatusOK {
-		return "", fmt.Errorf("kroki returned HTTP %d", resp.StatusCode)
+		return "", fmt.Errorf("kroki returned HTTP %d — try a local instance: docker run -d -p 8000:8000 yuzutech/kroki", resp.StatusCode)
 	}
 
 	out, err := os.Create(cachePath)
@@ -62,6 +69,7 @@ func RenderDiagramViaKroki(lang, code string) (string, error) {
 	defer out.Close()
 
 	if _, err = io.Copy(out, resp.Body); err != nil {
+		_ = os.Remove(cachePath) // remove incomplete cache file
 		return "", fmt.Errorf("cache file write: %w", err)
 	}
 	return cachePath, nil