From a362d1eb5e09362ec89119772576e62e902e7c3c Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Wed, 14 Jan 2026 08:03:32 -0800 Subject: [PATCH 1/2] Fix examples.md template: escape comment markers and remove orphaned content --- docs/examples.md | 218 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 213 insertions(+), 5 deletions(-) diff --git a/docs/examples.md b/docs/examples.md index c084d48..2e0f380 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -12,6 +12,72 @@ Real-world examples demonstrating the power and flexibility of `markdown-code-ru Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + +``` + +After running `markdown-code-runner`: +```markdown +This is an example of a simple code block: + + + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + +``` + +### Example 2: Multiple code blocks + +```markdown +Here are two code blocks: + +First code block: + + + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + +``` + + +```markdown +Second code block: + + + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + +``` + +After running `markdown-code-runner`: + +```markdown +Here are two code blocks: + +First code block: + + + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + + +Second code block: + + + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + +``` + ## Usage Ideas @@ -22,20 +88,162 @@ Real-world examples demonstrating the power and flexibility of `markdown-code-ru -.*?", "", content, flags=re.DOTALL) --> + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py +### Idea 3: Generating Markdown Tables + +Use the `pandas` library to create a Markdown table from a DataFrame. The following example demonstrates how to create a table with random data: + +```python +import pandas as pd +import numpy as np + +# Generate random data +np.random.seed(42) +data = np.random.randint(1, 101, size=(5, 3)) + +# Create a DataFrame and column names +df = pd.DataFrame(data, columns=["Column A", "Column B", "Column C"]) + +# Convert the DataFrame to a Markdown table +print(df.to_markdown(index=False)) +``` + +Which is rendered as: + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + + +### Idea 4: Generating Visualizations + +Create a visualization using the `matplotlib` library and save it as an image. Then, reference the image in your Markdown file. The following example demonstrates how to create a bar chart. + +Using a triple-backtick code block: + + +```python +import matplotlib.pyplot as plt +import io +import base64 +from urllib.parse import quote + +# Example data for the plot +x = [1, 2, 3, 4, 5] +y = [2, 4, 6, 8, 10] + +# Create a simple line plot +plt.plot(x, y) +plt.xlabel("X-axis") +plt.ylabel("Y-axis") +plt.title("Sample Line Plot") + +# Save the plot to a BytesIO buffer +buf = io.BytesIO() +plt.savefig(buf, format='png') +plt.close() + +# Encode the buffer as a base64 string +data = base64.b64encode(buf.getvalue()).decode('utf-8') + +# Create an inline HTML img tag with the base64 string +from urllib.parse import quote +img_html = f'Sample Line Plot' + +print(img_html) +``` + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + + +> **NOTE**: This output is disabled here because GitHub Markdown doesn't support inline image HTML. This will work on other Markdown renderers. + +### Idea 5: Generating a table from CSV data + +Suppose you have a CSV file containing data that you want to display as a table in your Markdown file. +You can use `pandas` to read the CSV file, convert it to a DataFrame, and then output it as a Markdown table. + +Using a triple-backtick code block: + +```python +import pandas as pd +csv_data = "Name,Age,Score\nAlice,30,90\nBob,25,85\nCharlie,22,95" +with open("sample_data.csv", "w") as f: + f.write(csv_data) +df = pd.read_csv("sample_data.csv") +print(df.to_markdown(index=False)) +``` + +Which is rendered as: + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + + +### Idea 6: Displaying API data as a list + +You can use `markdown-code-runner` to make API calls and display the data as a list in your Markdown file. +In this example, we'll use the `requests` library to fetch data from an API and display the results as a list. + +Using a hidden code block: + + +```markdown + + + + + + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + + + +### Idea 7: Run a Rust program + +We can use `markdown-code-runner` to write Rust code to a file and then a hidden bash code block to run the code and display the output. + +The code below *is actually executed*, check out the [`README.md` in plain text](https://github.com/basnijholt/markdown-code-runner/blob/main/README.md?plain=1) to see how this works. + +```rust +fn main() { + println!("Hello, world!"); +} +``` + +Which when executed produces: + + + + + + + + + Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py + + +These are just a few examples of how you can use Markdown Code Runner to enhance your Markdown documents with dynamic content. The possibilities are endless! + + + ## More Ideas Here are additional creative uses for `markdown-code-runner`: ### Auto-Generate Package Statistics -```python markdown-code-runner +```python # Fetch package download statistics import requests @@ -46,7 +254,7 @@ print("Download statistics would appear here!") ### Document Your API -```python markdown-code-runner +```python # Auto-generate API documentation from docstrings import inspect from markdown_code_runner import update_markdown_file @@ -64,7 +272,7 @@ if doc: ### Include Test Results -```python markdown-code-runner +```python # Show test coverage or test results import subprocess result = subprocess.run( @@ -77,7 +285,7 @@ print(result.stdout) ### Dynamic Configuration Examples -```python markdown-code-runner +```python # Generate configuration examples from actual defaults print("Default markers used by markdown-code-runner:") print() From 5b3e4ae8520b355ee9d7dfc57451489699cbe791 Mon Sep 17 00:00:00 2001 From: Bas Nijholt Date: Wed, 14 Jan 2026 08:10:01 -0800 Subject: [PATCH 2/2] Remove orphaned content from examples.md template The previous commit accidentally included generated content that was outside the proper OUTPUT sections. This commit removes the orphaned markdown examples and keeps only the template structure with PLACEHOLDER text that gets replaced during CI builds. --- docs/examples.md | 213 +---------------------------------------------- 1 file changed, 4 insertions(+), 209 deletions(-) diff --git a/docs/examples.md b/docs/examples.md index 2e0f380..bf0341a 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -12,72 +12,6 @@ Real-world examples demonstrating the power and flexibility of `markdown-code-ru Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - -``` - -After running `markdown-code-runner`: -```markdown -This is an example of a simple code block: - - - - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - -``` - -### Example 2: Multiple code blocks - -```markdown -Here are two code blocks: - -First code block: - - - - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - -``` - - -```markdown -Second code block: - - - - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - -``` - -After running `markdown-code-runner`: - -```markdown -Here are two code blocks: - -First code block: - - - - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - - -Second code block: - - - - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - -``` - ## Usage Ideas @@ -98,152 +32,13 @@ Second code block: Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py -### Idea 3: Generating Markdown Tables - -Use the `pandas` library to create a Markdown table from a DataFrame. The following example demonstrates how to create a table with random data: - -```python -import pandas as pd -import numpy as np - -# Generate random data -np.random.seed(42) -data = np.random.randint(1, 101, size=(5, 3)) - -# Create a DataFrame and column names -df = pd.DataFrame(data, columns=["Column A", "Column B", "Column C"]) - -# Convert the DataFrame to a Markdown table -print(df.to_markdown(index=False)) -``` - -Which is rendered as: - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - - -### Idea 4: Generating Visualizations - -Create a visualization using the `matplotlib` library and save it as an image. Then, reference the image in your Markdown file. The following example demonstrates how to create a bar chart. - -Using a triple-backtick code block: - - -```python -import matplotlib.pyplot as plt -import io -import base64 -from urllib.parse import quote - -# Example data for the plot -x = [1, 2, 3, 4, 5] -y = [2, 4, 6, 8, 10] - -# Create a simple line plot -plt.plot(x, y) -plt.xlabel("X-axis") -plt.ylabel("Y-axis") -plt.title("Sample Line Plot") - -# Save the plot to a BytesIO buffer -buf = io.BytesIO() -plt.savefig(buf, format='png') -plt.close() - -# Encode the buffer as a base64 string -data = base64.b64encode(buf.getvalue()).decode('utf-8') - -# Create an inline HTML img tag with the base64 string -from urllib.parse import quote -img_html = f'Sample Line Plot' - -print(img_html) -``` - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - - -> **NOTE**: This output is disabled here because GitHub Markdown doesn't support inline image HTML. This will work on other Markdown renderers. - -### Idea 5: Generating a table from CSV data - -Suppose you have a CSV file containing data that you want to display as a table in your Markdown file. -You can use `pandas` to read the CSV file, convert it to a DataFrame, and then output it as a Markdown table. - -Using a triple-backtick code block: - -```python -import pandas as pd -csv_data = "Name,Age,Score\nAlice,30,90\nBob,25,85\nCharlie,22,95" -with open("sample_data.csv", "w") as f: - f.write(csv_data) -df = pd.read_csv("sample_data.csv") -print(df.to_markdown(index=False)) -``` - -Which is rendered as: - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - - -### Idea 6: Displaying API data as a list - -You can use `markdown-code-runner` to make API calls and display the data as a list in your Markdown file. -In this example, we'll use the `requests` library to fetch data from an API and display the results as a list. - -Using a hidden code block: - - -```markdown - - - - - - - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - - - -### Idea 7: Run a Rust program - -We can use `markdown-code-runner` to write Rust code to a file and then a hidden bash code block to run the code and display the output. - -The code below *is actually executed*, check out the [`README.md` in plain text](https://github.com/basnijholt/markdown-code-runner/blob/main/README.md?plain=1) to see how this works. - -```rust -fn main() { - println!("Hello, world!"); -} -``` - -Which when executed produces: - - - - - - - - - Output is generated during CI build. We don't commit generated content to keep docs copyable and avoid recursion. See docs/docs_gen.py - - -These are just a few examples of how you can use Markdown Code Runner to enhance your Markdown documents with dynamic content. The possibilities are endless! - - - ## More Ideas Here are additional creative uses for `markdown-code-runner`: ### Auto-Generate Package Statistics -```python +```python markdown-code-runner # Fetch package download statistics import requests @@ -254,7 +49,7 @@ print("Download statistics would appear here!") ### Document Your API -```python +```python markdown-code-runner # Auto-generate API documentation from docstrings import inspect from markdown_code_runner import update_markdown_file @@ -272,7 +67,7 @@ if doc: ### Include Test Results -```python +```python markdown-code-runner # Show test coverage or test results import subprocess result = subprocess.run( @@ -285,7 +80,7 @@ print(result.stdout) ### Dynamic Configuration Examples -```python +```python markdown-code-runner # Generate configuration examples from actual defaults print("Default markers used by markdown-code-runner:") print()