{"id":28435328,"url":"https://github.com/aurelienbottazini/markdown-run","last_synced_at":"2025-06-30T13:32:44.254Z","repository":{"id":293139664,"uuid":"983072289","full_name":"aurelienbottazini/markdown-run","owner":"aurelienbottazini","description":"Execute code blocks and inline results for your markdown files","archived":false,"fork":false,"pushed_at":"2025-06-09T07:58:00.000Z","size":3680,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-20T22:43:03.732Z","etag":null,"topics":["flamegraph","javascript","markdown","mermaid","postgresql","ruby","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aurelienbottazini.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-13T20:45:53.000Z","updated_at":"2025-06-09T07:58:03.000Z","dependencies_parsed_at":"2025-05-31T21:28:10.583Z","dependency_job_id":"0ee4ee0c-9fa1-4449-b557-560c6a4c958c","html_url":"https://github.com/aurelienbottazini/markdown-run","commit_stats":null,"previous_names":["aurelienbottazini/markdown-run"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/aurelienbottazini/markdown-run","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aurelienbottazini%2Fmarkdown-run","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aurelienbottazini%2Fmarkdown-run/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aurelienbottazini%2Fmarkdown-run/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aurelienbottazini%2Fmarkdown-run/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aurelienbottazini","download_url":"https://codeload.github.com/aurelienbottazini/markdown-run/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aurelienbottazini%2Fmarkdown-run/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261031677,"owners_count":23100027,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["flamegraph","javascript","markdown","mermaid","postgresql","ruby","sqlite3"],"created_at":"2025-06-05T20:08:08.072Z","updated_at":"2025-06-30T13:32:44.230Z","avatar_url":"https://github.com/aurelienbottazini.png","language":"Ruby","readme":"[![Ruby](https://github.com/aurelienbottazini/markdown-run/actions/workflows/main.yml/badge.svg)](https://github.com/aurelienbottazini/markdown-run/actions/workflows/main.yml) [![Gem Version](https://badge.fury.io/rb/markdown-run.svg)](https://badge.fury.io/rb/markdown-run)\n\n# Markdown-run\n\nExecute code blocks from your markdown files.\nSave results to a new code block appended after the initial code block.\nDo not rerun code blocks if result block is present.\n\nMeant to be used from the terminal or from an editor with a keybinding.\n\nSupported languages:\n\n- Javascript\n- Ruby\n- sqlite3\n- postgresql\n- bash\n- zsh\n- mermaid (generates SVG diagrams)\n\n## Installation\n\n`gem install markdown-run`\n\n## Usage\n\n- Run specs `markdown-run`\n- Run on a markdown file `markdown-run your-filename`\n\nexample vscode keybinding\n\n```json\n  {\n    \"key\": \"ctrl+shift+b\",\n    \"command\": \"runCommands\",\n    \"args\": {\n      \"commands\": [\n        {\n          \"command\": \"workbench.action.files.save\"\n        },\n        {\n          \"command\": \"workbench.action.terminal.sendSequence\",\n          \"args\": {\n            \"text\": \"markdown-run \\\"${file}\\\"\\n\"\n          }\n        },\n        {\n          \"command\": \"workbench.action.files.revert\"\n        }\n      ]\n    },\n    \"when\": \"editorTextFocus \u0026\u0026 editorLangId == 'markdown'\"\n  },\n```\n\n### Code block options\n\n- `run=true` or `run=false` to control whether a code block should be executed at all. `run=true` is the default if not specified\n- `rerun=true` or `rerun=false` to control whether a code block should be re-executed if a result block already exists. `rerun=false` is the default if not specified\n- `result=true` or `result=false` to control whether the result block should be displayed after execution. `result=true` is the default if not specified. When `result=false`, the code still executes but the result block is hidden\n- `explain=true` or `explain=false` for psql code blocks to generate query execution plans with Dalibo visualization links. `explain=false` is the default if not specified\n- `flamegraph=true` or `flamegraph=false` for psql code blocks to generate PostgreSQL query execution plan flamegraphs as SVG images. `flamegraph=false` is the default if not specified\n\nOptions can be combined. If `run=false` is specified, the code block will not execute regardless of the `rerun` setting. The `result` option only affects display of the result block, not code execution.\n\n### Standalone Option Syntax\n\nOptions can also be specified using standalone syntax without explicit `=true`:\n\n- `run` is equivalent to `run=true`\n- `rerun` is equivalent to `rerun=true`\n- `result` is equivalent to `result=true`\n- `explain` is equivalent to `explain=true`\n- `flamegraph` is equivalent to `flamegraph=true`\n\nExplicit assignments (e.g., `run=false`) take precedence over standalone options.\n\nExamples:\n\n```js run=false\nconsole.log(\"This will not execute at all\");\n```\n\n```js rerun\nconsole.log(\"This will re-execute even if result exists\");\n```\n\n```js run=true rerun=false\nconsole.log(\"This will execute only if no result exists\");\n```\n\n```ruby result=false run\nputs \"This executes but the result block is hidden\"\n```\n\n```psql explain\nSELECT * FROM users WHERE id = 1;\n```\n\n```psql explain=true\nEXPLAIN (ANALYZE) SELECT * FROM large_table;\n```\n\n```psql flamegraph\nSELECT u.name, COUNT(o.id) as order_count\nFROM users u\nLEFT JOIN orders o ON u.id = o.user_id\nWHERE u.created_at \u003e '2024-01-01'\nGROUP BY u.id, u.name\nORDER BY order_count DESC\nLIMIT 10;\n```\n\n```psql flamegraph=true result=false\n-- This will generate a flamegraph but hide the JSON result block\nSELECT * FROM complex_query_with_joins;\n```\n\n```psql result=false explain\nSELECT * FROM large_table;\n-- This will execute the explain query and show the Dalibo link but hide the result block\n```\n\n### PostgreSQL Flamegraphs\n\nPostgreSQL flamegraph blocks generate interactive SVG flamegraphs from query execution plans:\n\n```psql flamegraph\nSELECT users.*, orders.total\nFROM users\nJOIN orders ON users.id = orders.user_id\nWHERE users.created_at \u003e '2024-01-01';\n```\n\nThis generates:\n\n- An SVG flamegraph file in a directory named after the markdown file\n- Filename format: `my-document-flamegraph-20250118-143022-a1b2c3.svg`\n- Embedded image tag: `![PostgreSQL Query Flamegraph](my-document/my-document-flamegraph-20250118-143022-a1b2c3.svg)`\n\n**Flamegraph features:**\n\n- **Interactive**: Hover over rectangles to see detailed timing information\n- **Color-coded**: Different colors for operation types (red=seq scans, green=index scans, blue=joins, etc.)\n- **Hierarchical**: Shows query plan structure visually\n- **Performance insights**: Width represents execution time, making bottlenecks immediately visible\n\n**What flamegraphs help identify:**\n\n- Slow operations (widest rectangles)\n- Query plan structure (nested relationships)\n- Inefficient operations (color-coded by type)\n- Execution time distribution across plan nodes\n\n### Mermaid diagrams\n\nMermaid blocks generate SVG files and insert markdown image tags:\n\n```mermaid\ngraph TD\n    A[Start] --\u003e B[Process]\n    B --\u003e C[End]\n```\n\nThis generates an SVG file in a directory named after the markdown file, with a filename that includes the markdown file's basename and a timestamp:\n\n- Directory: `my-document/` (if the markdown file is `my-document.md`)\n- Filename: `my-document-20250602-215507-a1289a799c29.svg`\n- Image tag: `![Mermaid Diagram](my-document/my-document-20250602-215507-a1289a799c29.svg)`\n\nNote: Requires `@mermaid-js/mermaid-cli` to be installed: `npm install -g @mermaid-js/mermaid-cli`\n\n## Frontmatter\n\nYou can add a yaml frontmatter to redefine code block behavior.\n\nFor example sql blocks run by default against sqlite\nTo have them run with postgres you can add at the top of your markdown file:\n\n```yaml\nmarkdown-run:\n  alias:\n    - sql: psql\n```\n\n### Setting Defaults\n\nYou can override the default behavior for code block options using frontmatter:\n\n```yaml\nmarkdown-run:\n  defaults:\n    rerun: true\n    result: false\n  psql:\n    explain: true\n  ruby:\n    rerun: false\n```\n\n**Priority order (highest to lowest):**\n\n1. Explicit options in code blocks (e.g., `rerun=true`)\n2. Language-specific defaults (e.g., `psql: { explain: true }`)\n3. Global defaults (e.g., `defaults: { rerun: true }`)\n4. Built-in application defaults\n\n**Available options for defaults:**\n\n- `run`: Control whether code blocks execute (default: `true`)\n- `rerun`: Control whether to re-execute if result exists (default: `false`)\n- `result`: Control whether to show result blocks (default: `true`)\n- `explain`: For psql blocks, generate explain plans (default: `false`)\n- `flamegraph`: For psql blocks, generate flamegraph SVGs (default: `false`)\n\n**Examples:**\n\nMake all code blocks rerun by default:\n\n```yaml\nmarkdown-run:\n  defaults:\n    rerun: true\n```\n\nHide result blocks by default but enable explain for psql:\n\n```yaml\nmarkdown-run:\n  defaults:\n    result: false\n  psql:\n    explain: true\n```\n\nEnable flamegraphs by default for all psql blocks:\n\n```yaml\nmarkdown-run:\n  psql:\n    flamegraph: true\n```\n\nLanguage-specific settings override global defaults:\n\n```yaml\nmarkdown-run:\n  defaults:\n    rerun: false # Global default\n  ruby:\n    rerun: true # Ruby blocks will rerun, others won't\n```\n\n## Demo\n\n![VSCode Usage](docs/markdown-run-vscode.gif)\n\n## Development\n\nJust run the script with `./exe/markdown-run`\n\n## Contributing\n\nBug reports are welcome on GitHub at https://github.com/aurelienbottazini/markdown-run.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## [Code of conduct](https://github.com/aurelienbottazini/markdown-run/blob/main/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faurelienbottazini%2Fmarkdown-run","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faurelienbottazini%2Fmarkdown-run","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faurelienbottazini%2Fmarkdown-run/lists"}