lint

Author: John Lyu

docs/usage/caching.md

@@ -14,7 +14,7 @@ When generating images, charts, or running expensive computations in your docume
 
 All cached results are stored in `.markdown-exec-cache/` in your project root directory:
 
-```
+```sh
 your-project/
 ├── docs/
 ├── mkdocs.yml
@@ -62,19 +62,21 @@ The cache file will be stored as `.markdown-exec-cache/my-plot.cache`.
 
 To force re-execution and update the cache for a specific code block, use `refresh="yes"`:
 
-```markdown
+````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.
+**`refresh="yes"`** forces re-execution but **keeps the cache enabled** - it updates the cached result for future builds.
+
+```bash
+**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
 
@@ -91,6 +93,7 @@ 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
@@ -116,68 +119,79 @@ 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:
+
+1. **Cache Lookup**: Before execution, the filesystem cache is checked for a matching entry
+
+1. **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
+
+1. **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**:
+1. **Use refresh temporarily**:
+
    ```markdown
    cache="my-plot" refresh="yes"  # Remove refresh="yes" after update
    ```
 
-3. **Use global refresh** for all caches:
+1. **Use global refresh** for all caches:
+
    ```bash
    MARKDOWN_EXEC_CACHE_REFRESH=1 mkdocs build
    ```
 
-4. **Clear cache directory** before important builds:
+1. **Clear cache directory** before important builds:
+
    ```bash
    rm -rf .markdown-exec-cache/
    ```
@@ -223,14 +237,14 @@ print(f"⭐ **{stars}** stars on GitHub!")
 ### 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/`
+1. Check that you're using `cache="yes"` or a custom ID
+1. 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
+1. Delete the specific cache file
+1. Clear the entire cache directory
 
 ### Large Cache Directory