feat: Add filesystem-only caching with global refresh support

- Implement CacheManager class for code execution result caching
- Support hash-based caching (automatic invalidation on code changes)
- Support custom cache IDs for cross-build persistence
- Add MARKDOWN_EXEC_CACHE_REFRESH environment variable for global refresh
- Add refresh option to force cache updates per code block
- Store cache files in .markdown-exec-cache/ directory
- Add comprehensive test suite with 14 cache-specific tests
- Add caching documentation with usage examples
- Update README with caching quickstart
- Isolate test cache directories to prevent pollution

This improves documentation build performance by caching expensive
operations like plot generation, API calls, and computations.

Author: PaleNeutron

.gitignore

@@ -23,3 +23,4 @@ uv.lock
 .mypy_cache/
 .ruff_cache/
 __pycache__/
+.markdown-exec-cache/

README.md

@@ -111,6 +111,41 @@ grep extra_css README.md && exit 2
 ```
 ````
 
+### Caching
+
+Speed up your builds by caching execution results:
+
+````md
+```python exec="yes" cache="yes"
+# Expensive computation
+import time
+time.sleep(5)
+print("Done!")
+```
+````
+
+Use custom cache IDs for persistence across builds:
+
+````md
+```python exec="yes" cache="my-plot"
+# Generate plot - will be cached
+import matplotlib.pyplot as plt
+# ...
+```
+````
+
+Force cache refresh with `refresh="yes"`:
+
+````md
+```python exec="yes" cache="my-plot" refresh="yes"
+# This will always re-execute
+```
+````
+
+See [caching documentation](https://pawamoy.github.io/markdown-exec/usage/caching/) for more details.
+
+---
+
 See [usage](https://pawamoy.github.io/markdown-exec/usage/) for more details,
 and the [gallery](https://pawamoy.github.io/markdown-exec/gallery/) for more examples!
 

docs/usage/caching.md

@@ -0,0 +1,245 @@
+# Caching
+
+Markdown Exec supports filesystem-based caching of code execution results to speed up documentation builds and development workflows.
+
+## Overview
+
+When generating images, charts, or running expensive computations in your documentation, re-executing the same code on every build can significantly slow down the rendering process. The caching feature allows you to:
+
+- **Speed up builds**: Reuse previously computed results instead of re-executing code
+- **Persist across builds**: All cache is stored on the filesystem for cross-build persistence
+- **Global cache refresh**: Force refresh of all cached results with a single environment variable
+
+## Cache Storage
+
+All cached results are stored in `.markdown-exec-cache/` in your project root directory:
+
+```
+your-project/
+├── docs/
+├── mkdocs.yml
+└── .markdown-exec-cache/
+    ├── my-plot.cache          # Custom ID cache
+    └── abc123def456.cache      # Hash-based cache files
+```
+
+Add this directory to your `.gitignore`:
+
+```gitignore
+.markdown-exec-cache/
+```
+
+## Usage
+
+### Hash-Based Caching
+
+Enable caching by adding `cache="yes"` to your code block. A hash is computed from the code content and execution options:
+
+````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
+```python exec="yes" cache="yes"
+import time
+print(f"Executed at: {time.time()}")
+```
+````
+
+The cache is automatically invalidated when the code or execution options change.
+
+### Custom Cache IDs
+
+For more control, use a custom cache ID (string value). This is useful for expensive operations where you want explicit control over cache invalidation:
+
+````md exec="1" source="tabbed-left" tabs="Markdown|Rendered"
+```python exec="yes" cache="my-plot"
+import matplotlib.pyplot as plt
+# Expensive plot generation...
+print("Generated plot")
+```
+````
+
+The cache file will be stored as `.markdown-exec-cache/my-plot.cache`.
+
+### Cache Invalidation
+
+To force re-execution and update the cache for a specific code block, use `refresh="yes"`:
+
+```markdown
+```python exec="yes" cache="my-plot" refresh="yes"
+# This will always re-execute and update the cache
+print("Fresh execution!")
+```
+```
+
+!!! note "refresh vs removing cache"
+    **`refresh="yes"`** forces re-execution but **keeps the cache enabled** - it updates the cached result for future builds.
+    
+    **Removing `cache` option** completely disables caching - the code executes every time with no caching at all.
+    
+    Use `refresh="yes"` when you want to update stale cache but keep caching benefits for subsequent builds.
+
+### Global Cache Refresh
+
+To refresh **all** cached results at once, set the `MARKDOWN_EXEC_CACHE_REFRESH` environment variable:
+
+```bash
+# Force refresh all caches during build
+MARKDOWN_EXEC_CACHE_REFRESH=1 mkdocs build
+
+# Or with other truthy values
+MARKDOWN_EXEC_CACHE_REFRESH=yes mkdocs build
+MARKDOWN_EXEC_CACHE_REFRESH=true mkdocs build
+MARKDOWN_EXEC_CACHE_REFRESH=on mkdocs build
+```
+
+This is useful for:
+- CI/CD pipelines where you want fresh builds
+- Ensuring all documentation is up-to-date
+- Debugging cache-related issues
+
+## Clearing Cache
+
+### Delete Specific Cache Entry
+
+Remove the cache file for a specific custom ID:
+
+```bash
+rm .markdown-exec-cache/my-custom-id.cache
+```
+
+### Clear All Cache
+
+Remove the entire cache directory:
+
+```bash
+rm -rf .markdown-exec-cache/
+```
+
+## How It Works
+
+1. **Hash Computation**: For `cache="yes"`, a SHA-256 hash is computed from:
+   - The code content
+   - Execution options (language, HTML mode, working directory, etc.)
+   
+2. **Cache Lookup**: Before execution, the filesystem cache is checked for a matching entry
+   
+3. **Execution & Storage**: If no cached result is found:
+   - Code is executed
+   - Output is stored in the filesystem cache
+   
+4. **Cache Retrieval**: Cached output is used instead of re-executing the code
+
+## Best Practices
+
+### When to Use Caching
+
+✅ **Good use cases:**
+- Generating plots, diagrams, or images
+- Running expensive computations
+- Calling external APIs or services
+- Processing large datasets
+
+❌ **Avoid caching for:**
+- Simple print statements
+- Code demonstrating output variations
+- Time-sensitive or non-deterministic code
+
+### Choosing Cache Type
+
+- **`cache="yes"`** (hash-based):
+  - Automatically invalidated when code changes
+  - Great for development and production
+  - No manual cache management needed
+
+- **`cache="custom-id"`** (custom ID):
+  - Use for expensive operations where you want explicit control
+  - Easier to identify and manage specific cache files
+  - Requires manual invalidation or `refresh="yes"` when code changes
+
+### Cache Invalidation Strategy
+
+**For hash-based caching (`cache="yes"`):**
+- Cache is automatically invalidated when code or options change
+- No manual intervention needed
+
+**For custom ID caching (`cache="custom-id"`):**
+
+1. **Change the ID** when you want to force re-execution:
+   ```markdown
+   cache="my-plot-v2"  # Changed from my-plot
+   ```
+
+2. **Use refresh temporarily**:
+   ```markdown
+   cache="my-plot" refresh="yes"  # Remove refresh="yes" after update
+   ```
+
+3. **Use global refresh** for all caches:
+   ```bash
+   MARKDOWN_EXEC_CACHE_REFRESH=1 mkdocs build
+   ```
+
+4. **Clear cache directory** before important builds:
+   ```bash
+   rm -rf .markdown-exec-cache/
+   ```
+
+## Examples
+
+### Caching a Matplotlib Plot
+
+````markdown
+```python exec="yes" html="yes" cache="population-chart"
+import matplotlib.pyplot as plt
+import io
+import base64
+
+# Expensive plot generation
+fig, ax = plt.subplots()
+ax.plot([1, 2, 3], [1, 4, 9])
+ax.set_title("Population Growth")
+
+# Save to base64
+buffer = io.BytesIO()
+plt.savefig(buffer, format='png')
+buffer.seek(0)
+img_str = base64.b64encode(buffer.read()).decode()
+print(f'<img src="data:image/png;base64,{img_str}"/>')
+plt.close()
+```
+````
+
+### Caching API Calls
+
+````markdown
+```python exec="yes" cache="github-stars" refresh="no"
+import requests
+response = requests.get("https://api.github.com/repos/pawamoy/markdown-exec")
+stars = response.json()["stargazers_count"]
+print(f"⭐ **{stars}** stars on GitHub!")
+```
+````
+
+## Troubleshooting
+
+### Cache Not Working
+
+1. Ensure the cache directory is writable
+2. Check that you're using `cache="yes"` or a custom ID
+3. Verify the cache directory exists: `ls -la .markdown-exec-cache/`
+
+### Stale Cache Results
+
+1. Use `refresh="yes"` to force re-execution
+2. Delete the specific cache file
+3. Clear the entire cache directory
+
+### Large Cache Directory
+
+Cache files accumulate over time. Periodically clean up:
+
+```bash
+# See cache directory size
+du -sh .markdown-exec-cache/
+
+# Remove all cache files
+rm -rf .markdown-exec-cache/
+```

mkdocs.yml

@@ -25,6 +25,7 @@ nav:
   - Pyodide: usage/pyodide.md
   - Shell: usage/shell.md
   - Tree: usage/tree.md
+  - Caching: usage/caching.md
 - Gallery: gallery.md
 - API reference: reference/api.md
 - Development:

src/markdown_exec/__init__.py

@@ -3,6 +3,7 @@
 Utilities to execute code blocks in Markdown files.
 """
 
+from markdown_exec._internal.cache import CacheManager, get_cache_manager
 from markdown_exec._internal.formatters.base import (
     ExecutionError,
     base_format,
@@ -29,6 +30,7 @@
 
 __all__ = [
     "MARKDOWN_EXEC_AUTO",
+    "CacheManager",
     "ExecutionError",
     "HeadingReportingTreeprocessor",
     "IdPrependingTreeprocessor",
@@ -43,6 +45,7 @@
     "default_tabs",
     "formatter",
     "formatters",
+    "get_cache_manager",
     "get_logger",
     "markdown_config",
     "patch_loggers",