{"id":23763517,"url":"https://github.com/tomashubelbauer/markright","last_synced_at":"2025-09-05T08:32:59.824Z","repository":{"id":107986205,"uuid":"307311867","full_name":"TomasHubelbauer/markright","owner":"TomasHubelbauer","description":"Didactic literate programming","archived":false,"fork":false,"pushed_at":"2024-10-28T23:01:10.000Z","size":237,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-11-26T17:45:22.930Z","etag":null,"topics":["lab-notebook","literate-programming","markdown","markright","notebook","notebooks"],"latest_commit_sha":null,"homepage":"https://markright.net","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TomasHubelbauer.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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}},"created_at":"2020-10-26T08:52:11.000Z","updated_at":"2024-10-28T23:01:14.000Z","dependencies_parsed_at":"2024-11-26T17:42:57.592Z","dependency_job_id":null,"html_url":"https://github.com/TomasHubelbauer/markright","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fmarkright","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fmarkright/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fmarkright/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TomasHubelbauer%2Fmarkright/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TomasHubelbauer","download_url":"https://codeload.github.com/TomasHubelbauer/markright/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232032116,"owners_count":18462972,"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":["lab-notebook","literate-programming","markdown","markright","notebook","notebooks"],"created_at":"2024-12-31T22:12:51.584Z","updated_at":"2024-12-31T22:12:52.127Z","avatar_url":"https://github.com/TomasHubelbauer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MarkRight\n\nMarkRight is a tool for didactic literate programming.\n\nIt works by scanning a MarkDown files for fenced code blocks adorned with extra\ninstructions and acting on those instructions to execute code, create files etc.\n\nThe artifact of the MarkRight document exection might be a file, a program or a\nprocess that has happened and left desirable side effects.\n\nMarkRight documents are primarily append-only capturing new changes to apply to\nthe existing instructions and their artifacts.\n\n## Examples\n\nBy default, MarkRight will ignore code blocks which lack a language tag or whose\nlanguage tag it doesn't have support for.\n\nA code block like this will have no effect:\n\n~~~\n```\nHello, world!\n```\n~~~\n\nMarkRight will exit with empty output upon executing such a document.\n\nThe most basic example of a MarkRight document that would give output would be\nthis document where the code block has the special `stdout` language tag:\n\n~~~\n```stdout\nHello, world!\n```\n~~~\n\nRun `markright demo/stdout/readme.md` or `markright demo/stdout` to execute this\nexample.\n\nThe `stdout` language tag instructs MarkRight to dump the code block's text to\nthe standard output stream of the MarkRight process.\n\n`stderr` is supported with analoguous behavior for the standard error stream and\nthere is a respective example of this in `demo/stderr`.\nThe standard error lines appear in red and you can verify they are in stderr by\nsplitting the I/O streams and writing them into respective files:\n`markright demo/stderr 2\u003e\u003e error 1\u003e\u003e output`.\n\nSee [Handlers](#handlers) for the list of supported language tag handlers.\n\nAnother similar example would be the JavaScript Hello World expression one in\n`demo/javascript-expression` which demonstrates that JavaScript code blocks that\nproduce output redirect their output to MarkRight's output stream.\n\nSee also `demo/javascript-exception` to see the special-cased behavior of\nexceptions getting written to the standard error stream.\n\nNote that by default MarkRight looks for a `readme.md` file in the current\ndirectory.\n\nMarkRight code blocks can also create and update files.\nTo create a file, prepend a code span with the file name suffixed by a colon\natop the code block it relates to with nothing but whitespace in between:\n\n~~~\n`file-name.ext`:\n\n```\nHello, world!\n```\n~~~\n\nThis code block's text will get written to `file-name.ext` even though it has no\nlanguage tag, because it have an associated path.\nIf there was a language tag, its handler's standard streams would get redirected\nto the file.\n\n## Handlers\n\n### `txt`\n\nAlias for the `stdout` language tag.\nUseful for forcing the code block to be included in the output which it wouldn't\nwithout a language tag.\nShorter than `stdout` and without the `stdout`/`stderr` parity baggage if only\nthe former is used in the document.\nImplied when the code block has an associated path even if it has no language\ntag.\n\n### `stdout`\n\nWrites the code block's text to the MarkRight's standard output I/O stream.\n\n### `stderr`\n\nWrites the code block's text to the MarkRight's standard error I/O stream.\n\n### `js` / `javascript`\n\nEvaluates the code block as JavaScript using Bun's `eval` function.\nWrites the output of the last expression, if any, to standard output, unless an\nexception was thrown, in which case it gets written to standard error.\n\nNote that this handler uses `eval` and as such does not support `async`/`await`.\nSee https://github.com/oven-sh/bun/issues/14873 for more information.\n\nNote that JSX is not supported.\n\n### `ts` / `typescript`\n\nTranspiles the provided TypeScript code to JavaScript using Bun's transpiler and\nexecutes it using the JavaScript handler.\n\nNote that TLS and JSX is not supported, see the JavaScript handler section for\nmore information.\n\nNote that Bun doesn't support evaluating TypeScript directly yet, see here:\nhttps://github.com/oven-sh/bun/issues/11976\n\n## Development\n\nRun tests using `bun test`.\nUse `.only` to work on individual tests.\n\nRun using `bun .` to run on `readme.md` or `bun . /directory/file.md` to run on\na non-default document.\n\n## To-Do\n\n### Return GitHub Actions workflow and its corresponding readme badge\n\n- Use Bun GitHub Actions support\n- Run the unit tests\n- Run Bun's bundler to product executables for all platforms\n- Bump `package.json` version using `bun version patch` if supported\n- Stage the `package.json` Git change\n- Use `jq` to query the new version\n- Use `actions/create-release` to create a new release with the version\n- Use `actions/upload-release-asset` to upload the platform executables\n- Commit and push the `package.json` change\n\n### Distribute to JSR or maybe even NPM as an executable package\n\nDo this in a Bun-friendly way, something easy, not a PITA.\n\n### Add a `--watch` command to keep watching the file for changes\n\nClear the terminal in between runs.\n\n### Improve the parser to not require duplicating mode sigils with inline path\n\nCurrently `tag ..file-name.ext` is needed to specify a tag and the inline path\nwhile also distinguishing it from the meta.\n\nDoing it this way simplifies the parser implementation but makes for a worse\nuser experience.\nIt is a worthwhile trade-off for now, but should be improved down the line.\n\nOne option to solve this would be to require the paths to start with a period\nlike in ESM path module specifiers, but I don't like that option too much.\n\n### Add unit tests for the demo files\n\nCreate a wrapper to catch `console.log` and `console.error` calls like I already\ndo in `processBlocks` and compare the expected output with the real output.\n\nIn file management demos, also check the files on disk and clean up after.\n\n### Find a way to allow `diff`/`patch` code blocks to not have hunk context line\n\nThe `@@` line.\nThe `patch` utility seems to require these, it will not try to match and patch\nloosely.\nThe `git apply` command has `--unidiff-zero` which seems to allow not providing\nthe context lines but it was giving me trouble probably because the file I am\ntrying to apply to is not necessarily tracked by Git?\n\nIf there is no way to get rid of these, maybe I could generate the hunk context\nby assuming the changes are for the whole file?\nThis would massively lessen the utility of this code block though.\nMaybe there is a path where I derive the start and end lines and only require\nthat the diff/patch code is a single hunk maybe?\n\n### Consider allowing to specify what shell to use in the shell handler\n\nSupport the `bash`, `zsh` etc. language tags and take the choice of the shell\ninto an account in the execution.\n\nAdd examples that showcase the various shell's features to prove they shell\nselection works.\n\n### Return support for the Windows Sandbox feature\n\nRun PowerShell scripts in the Windows Sandbox and get back their outputs.\nAlso maybe file manage in the Windows Sandbox?\n\n### Recover the CLI calculator example and reimplement it in Bun\n\nOnce I have the file management sigils and operations figured out, I should be\nable to reimplement that example in MarkRight again with the new version running\non Bun to showcase the features it uses.\n\nhttps://raw.githubusercontent.com/TomasHubelbauer/markright/4fbead6a0b5a769d3ab04f1e3cb0c91b82df0e00/example/node-cli-calculator/readme.md\n\n### Add support for leaving out `diff`/`patch` meta and the `_` sigil\n\nWhen multiple code blocks in a row operate on the same file, it would be a pain\nto keep repeating its name, so let's make these two changes:\n\n1. Add the `_` sigil to code blocks without external path which makes the block\n   inherit the path of the last block that had a path\n2. Allow the `diff` and `patch` blocks to not specify `meta` in which case the\n   path of the last block that had a path is used\n3. Make code blocks without external path assume the path of the last block that\n   had a path when they use the `!` or `?` sigil\n\n### Add a subcommand to take in the difference between the file and the document\n\nWhen the user goes and runs the document, then changes the files, make this new\nsubcommand determine the differences between what is there and what MarkRight\nhad generated and add the diffs at the end of the document.\n\n### Make a VS Code extension for automatically colleting MarkRight changes\n\nThis is related to the above task about bringing in diffs after user made edits\nto the artifacts MarkRight dropped.\nMake it possible to just work on files and have the MarkRight document be built\nfor you with the possibility to jump in and add your comments as needed.\n\n### Consider adding a new file management sigil to tee to file and terminal both\n\nThis could be useful?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomashubelbauer%2Fmarkright","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftomashubelbauer%2Fmarkright","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftomashubelbauer%2Fmarkright/lists"}