fixup! feat: Add filesystem-only caching with global refresh support

Author: John Lyu

docs/usage/caching.md

@@ -19,7 +19,6 @@ your-project/
 ├── docs/
 ├── mkdocs.yml
 └── .markdown-exec-cache/
-    ├── my-plot.cache          # Custom ID cache
     └── abc123def456.cache      # Hash-based cache files
 ```
 
@@ -44,20 +43,6 @@ 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
 
 The cache is automatically invalidated when the code content or execution options change (a new hash is computed). **Stale cache files** — from code blocks that have been removed or changed — are cleaned up automatically:
@@ -85,16 +70,6 @@ This is useful for:
 
 ## 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
@@ -136,57 +111,24 @@ rm -rf .markdown-exec-cache/
 
 ### 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
+Use `cache="yes"` for all caching needs. The cache is automatically invalidated when the code or execution options change — no manual cache management needed.
 
 ### Cache Invalidation Strategy
 
-**For hash-based caching (`cache="yes"`):**
+Cache is automatically invalidated when code or options change — no manual intervention needed. To force re-execution of all cached blocks, use:
 
-- 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
-   ```
-
-1. **Use refresh temporarily**:
-
-   ```markdown
-   cache="my-plot" refresh="yes"  # Remove refresh="yes" after update
-   ```
-
-1. **Use global refresh** for all caches:
-
-   ```bash
-   MARKDOWN_EXEC_CACHE_REFRESH=1 mkdocs build
-   ```
-
-1. **Clear cache directory** before important builds:
+```bash
+MARKDOWN_EXEC_CACHE_REFRESH=1 mkdocs build
+```
 
-   ```bash
-   rm -rf .markdown-exec-cache/
-   ```
+Or [clear the cache directory](#clearing-cache) before the build.
 
 ## Examples
 
 ### Caching a Matplotlib Plot
 
 ````markdown
-```python exec="yes" html="yes" cache="population-chart"
+```python exec="yes" html="yes" cache="yes"
 import matplotlib.pyplot as plt
 import io
 import base64
@@ -206,17 +148,6 @@ 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

src/markdown_exec/_internal/cache.py

@@ -73,29 +73,25 @@ def _compute_hash(self, code: str, **options: Any) -> str:
         )
         return hashlib.sha256(cache_key.encode()).hexdigest()
 
-    def _get_cache_path(self, cache_id: str) -> Path:
+    def _get_cache_path(self, cache_key: str) -> Path:
         """Get the filesystem path for a cache entry.
 
         Parameters:
-            cache_id: The cache identifier (hash or custom ID).
+            cache_key: The cache key (hash).
 
         Returns:
             Path to the cache file.
         """
-        # Sanitize the cache_id to prevent path traversal
-        safe_id = "".join(c if c.isalnum() or c in "-_" else "_" for c in cache_id)
-        return self.cache_dir / f"{safe_id}.cache"
+        return self.cache_dir / f"{cache_key}.cache"
 
     def get(
         self,
-        cache_id: str | None,
         code: str,
         **options: Any,
     ) -> str | None:
         """Retrieve cached output for the given code.
 
         Parameters:
-            cache_id: Custom cache identifier, or None to use hash-based caching.
             code: The source code.
             **options: Execution options used for hash computation.
 
@@ -107,8 +103,7 @@ def get(
             _logger.debug("Global cache refresh active, forcing re-execution")
             return None
 
-        # Determine the cache key
-        cache_key = self._compute_hash(code, **options) if cache_id is None else cache_id
+        cache_key = self._compute_hash(code, **options)
 
         # Check filesystem cache
         cache_path = self._get_cache_path(cache_key)
@@ -127,21 +122,18 @@ def get(
 
     def set(
         self,
-        cache_id: str | None,
         code: str,
         output: str,
         **options: Any,
     ) -> None:
         """Store output in cache for the given code.
 
         Parameters:
-            cache_id: Custom cache identifier, or None to use hash-based caching.
             code: The source code.
             output: The execution output to cache.
             **options: Execution options used for hash computation.
         """
-        # Determine the cache key
-        cache_key = self._compute_hash(code, **options) if cache_id is None else cache_id
+        cache_key = self._compute_hash(code, **options)
 
         # Write to filesystem cache
         cache_path = self._get_cache_path(cache_key)
@@ -169,29 +161,14 @@ def cleanup_stale(self) -> None:
                 except OSError as error:
                     _logger.warning("Failed to delete stale cache file %s: %s", cache_file, error)
 
-    def clear(self, cache_id: str | None = None) -> None:
-        """Clear the filesystem cache.
-
-        Parameters:
-            cache_id: Specific cache ID to clear, or None to clear all.
-        """
-        if cache_id is None:
-            # Clear all cache files
-            for cache_file in self.cache_dir.glob("*.cache"):
-                try:
-                    cache_file.unlink()
-                    _logger.debug("Deleted cache file: %s", cache_file)
-                except OSError as error:
-                    _logger.warning("Failed to delete cache file %s: %s", cache_file, error)
-        else:
-            # Clear specific cache file
-            cache_path = self._get_cache_path(cache_id)
-            if cache_path.exists():
-                try:
-                    cache_path.unlink()
-                    _logger.debug("Deleted cache file: %s", cache_path)
-                except OSError as error:
-                    _logger.warning("Failed to delete cache file %s: %s", cache_path, error)
+    def clear(self) -> None:
+        """Clear all cached files."""
+        for cache_file in self.cache_dir.glob("*.cache"):
+            try:
+                cache_file.unlink()
+                _logger.debug("Deleted cache file: %s", cache_file)
+            except OSError as error:
+                _logger.warning("Failed to delete cache file %s: %s", cache_file, error)
 
 
 # Global cache manager instance

src/markdown_exec/_internal/formatters/base.py

@@ -106,7 +106,7 @@ def base_format(
     update_toc: bool = True,
     workdir: str | None = None,
     width: int | None = None,
-    cache: bool | str = False,
+    cache: bool = False,
     **options: Any,
 ) -> Markup:
     """Execute code and return HTML.
@@ -130,8 +130,7 @@ def base_format(
         update_toc: Whether to include generated headings
             into the Markdown table of contents (toc extension).
         workdir: The working directory to use for the execution.
-        cache: Whether to enable caching. If True, uses hash-based caching.
-            If a string, uses that string as a custom cache ID for cross-build persistence.
+        cache: Whether to enable caching.
         **options: Additional options passed from the formatter.
 
     Returns:
@@ -150,8 +149,6 @@ def base_format(
     output = None
     if cache:
         cache_manager = get_cache_manager()
-        cache_id = cache if isinstance(cache, str) else None
-
         # Build cache options (exclude cache itself and other non-execution options)
         cache_options = {
             "language": language,
@@ -163,7 +160,7 @@ def base_format(
             "extra": extra,
         }
 
-        output = cache_manager.get(cache_id, source_input, **cache_options)
+        output = cache_manager.get(source_input, **cache_options)
         if output is not None:
             _logger.debug("Using cached output for code block")
 
@@ -186,7 +183,7 @@ def base_format(
 
         # Cache the output if caching is enabled
         if cache:
-            cache_manager.set(cache_id, source_input, output, **cache_options)
+            cache_manager.set(source_input, output, **cache_options)
 
     if not output and not source:
         return Markup()

src/markdown_exec/_internal/main.py

@@ -77,13 +77,8 @@ def validator(
     workdir_value = inputs.pop("workdir", None)
     width_value = int(inputs.pop("width", "0"))
 
-    # Handle cache option: can be boolean or custom string ID
     cache_value = inputs.pop("cache", "")
-    cache_enabled = (
-        _to_bool(cache_value)
-        if cache_value.lower() in {"yes", "on", "true", "1", "no", "off", "false", "0", ""}
-        else cache_value
-    )
+    cache_enabled = _to_bool(cache_value)
 
     options["id"] = id_value
     options["id_prefix"] = id_prefix_value