Execute chunks of nushell code within markdown documents, write results back to your .md document or output them to the terminal.
numd is inspired by R Markdown.
# this block won't run as it has option `no-run` in its code fence
> git clone https://github.com/nushell-prophet/numd; cd numd
> nupm install --force --path . # optionally you can install this module via nupm
> use numd
> numd run README.md --no-savenumd run parses the initial file, generates a script to execute the found commands, executes this script in a new nushell instance, parses the results, updates the initial document accordingly, and/or outputs the resulting document into the terminal along with basic changes stats.
Experienced nushell users can understand the logic better by looking at examples. Especially, seeing numd in action describing its own commands.
numdlooks for```nushellor```nucode chunks.- In the code chunks, that entirely don't have lines starting with the
>symbol, numd executes the whole code chunks as they are, and if they produce any output (like inprint 'this'), then the output is written in the```output-numdchunks, next to the executed code chunks. - In the code chunks that contain one or more lines starting with
>symbol, numd filters only lines that start with the>or#symbol, executes those lines one by one and output their results just after the executed line.
use numd
numd run --helprun nushell code chunks in a markdown file, outputs results back to the `.md` and optionally to terminal
Usage:
> run {flags} <file>
Flags:
-o, --output-md-path <Filepath> - path to a resulting `.md` file; if omitted, updates the original file
--echo - output resulting markdown to the terminal
--no-backup - overwrite the existing `.md` file without backup
--no-save - do not save changes to the `.md` file
--no-info - do not output stats of changes in `.md` file
--intermid-script <Filepath> - optional a path for an intermediate script (useful for debugging purposes)
--no-fail-on-error - skip errors (and don't update markdown anyway)
--prepend-intermid <String> - prepend text (code) into the intermid script, useful for customizing nushell output settings
--diff - use diff for printing changes
-h, --help - Display the help message for this command
Parameters:
file <path>: path to a `.md` file containing nushell code to be executed
Input/output types:
╭──input──┬─output──╮
│ nothing │ nothing │
│ nothing │ string │
│ nothing │ record │
╰──input──┴─output──╯
numd understands the following block options. Several commaseparated block options will be combined together.
The block options should be in the infostring of the opening code fence like the example: ```nushell try, new-instance
numd code-block-options --list╭─────long──────┬─short─┬──────────────────description──────────────────╮
│ no-output │ O │ don't try printing result │
│ try │ t │ try handling errors │
│ new-instance │ n │ execute the chunk in the new nushell instance │
│ no-run │ N │ don't execute the code in chunk │
│ indent-output │ i │ indent the output visually │
╰─────long──────┴─short─┴──────────────────description──────────────────╯
By default numd provides basic stats on changes made.
numd run examples/1_simple_markdown/simple_markdown_with_no_output.md --no-save╭────────────────┬───────────────────────────────────╮
│ filename │ simple_markdown_with_no_output.md │
│ nu_code_blocks │ 3 │
│ levenstein │ 38 │
│ diff-lines │ +5 (20%) │
│ diff-words │ +7 (9.6%) │
│ diff-chars │ +38 (8.8%) │
╰────────────────┴───────────────────────────────────╯
Also --diff param can be used to display diff of changes.
numd run examples/1_simple_markdown/simple_markdown_with_no_output.md --diff --no-save --no-info// ls; # mind that this ls won't print in the markdown as it is used without `echo` or `>`
// $var1 | path join 'baz' 'bar'
// ```
// + ```output-numd
// + foo/baz/bar
// + ```
//
// ## Example 3
//
// ```nu
// # This chunk will output results inline
// > whoami
// + user
// > 2 + 2
// + 4
// ```
> numd clear-outputs --help
remove numd execution outputs from the file
Usage:
> clear-outputs {flags} <file>
Flags:
-o, --output-md-path <Filepath> - path to a resulting `.md` file; if omitted, updates the original file
--echo - output resulting markdown to the terminal instead of writing to file
--strip-markdown - keep only nushell script, strip all markdown tags
-h, --help - Display the help message for this command
Parameters:
file <path>: path to a `.md` file containing numd output to be cleared
Input/output types:
╭──input──┬─output──╮
│ nothing │ nothing │
│ nothing │ string │
│ nothing │ record │
╰──input──┴─output──╯numd can use the display_output hook to write the current sesssion prompts together with their output into a specified markdown file. There are corresponding commands numd capture start and numd capture stop.
> numd capture start --help
start capturing commands and their results into a file
Usage:
> start (file)
Flags:
-h, --help - Display the help message for this command
Parameters:
file <path>: (optional, default: 'numd_capture.md')
Input/output types:
╭──input──┬─output──╮
│ nothing │ nothing │
╰──input──┴─output──╯> numd capture stop --help
stop capturing commands and their results
Usage:
> stop
Flags:
-h, --help - Display the help message for this command
Input/output types:
╭──input──┬─output──╮
│ nothing │ nothing │
╰──input──┴─output──╯> ls examples | sort-by name | reject modified size
╭─────────────────name──────────────────┬─type─╮
│ examples/1_simple_markdown │ dir │
│ examples/2_numd_commands_explanations │ dir │
│ examples/3_book_types_of_data │ dir │
│ examples/4_book_working_with_lists │ dir │
╰─────────────────name──────────────────┴─type─╯
> sys | get host.boot_time
2024-04-07T05:26:21+00:00
> 2 + 2
4
> git tag | lines | sort -n | last
0.1.1numd run examples/1_simple_markdown/simple_markdown.md --echo --no-save
numd run examples/3_book_types_of_data/types_of_data.md --output-md-path examples/3_book_types_of_data/types_of_data_out.md --no-backup --intermid-script-path examples/3_book_types_of_data/types_of_data.md_intermid.nu