From f976860f3357660f121f038d13e9accee417751f Mon Sep 17 00:00:00 2001 From: Justin Lin Date: Fri, 25 Jul 2025 13:19:47 +1000 Subject: [PATCH] Add README --- README.md | 243 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 243 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3d64153 --- /dev/null +++ b/README.md @@ -0,0 +1,243 @@ +# mdsh: Run Shell Scripts in Markdown Templates + +Need repetitive document generation from CLI outputs? mdsh is what you need. + +Define your template in markdown format, and generate them on the fly! + +## Installation + +requirements: `go` installed + +```sh +git clone github.com/lancatlin/mdsh && cd mdsh +go build . +./mdsh examples/system-info.md +``` + +It will execute this template: + +~~~~markdown +--- +output: "sys-report.md" +--- + +# 💥 System Information Report for {{ sh "hostname" }} + +* **Hostname**: {{ sh "hostname" }} +* **Username**: {{ sh "whoami" }} +* **Uptime**: {{ sh "uptime -p" }} +* **System**: {{ sh "uname -a" }} +* **CPU**: {{ sh "uname -m" }} — {{ sh "nproc" }} cores +* **IP Address**: {{ sh "hostname -I || ip a | grep inet" }} +* **Default Gateway**: {{ sh "ip route | grep default || netstat -rn | grep default" }} + +--- + +## 🧠 Memory Usage + +{{ shell "free -h" }} + +--- + +## 📉 Disk Usage + +{{ shell "df -h /" }} + +--- + +Generated on: {{ sh "date" }} +~~~~ + +Then you will get `sys-report.md` like: + +~~~~markdown +# 💥 System Information Report for `fedora` + +* **Hostname**: `fedora` +* **Username**: `wancat` +* **Uptime**: `up 1 hour, 59 minutes` +* **System**: `Linux fedora 6.15.6-200.fc42.x86_64 #1 SMP PREEMPT_DYNAMIC Thu Jul 10 15:22:32 UTC 2025 x86_64 GNU/Linux` +* **CPU**: `x86_64` — `16` cores +* **IP Address**: `172.26.198.115 2405:dc00:ec83:ec80:af9c:87ed:9bae:bd0d` +* **Default Gateway**: `default via 172.26.198.50 dev wlp1s0 proto dhcp src 172.26.198.115 metric 600` + +--- + +## 🧠 Memory Usage + + +``` + total used free shared buff/cache available +Mem: 30Gi 7.5Gi 17Gi 234Mi 6.5Gi 23Gi +Swap: 8.0Gi 0B 8.0Gi + +``` + + +--- + +## 📉 Disk Usage + + +``` +Filesystem Size Used Avail Use% Mounted on +/dev/mapper/luks-d53d6eca-6a17-4120-bb6c-05c501334c6d 93G 58G 34G 64% / + +``` + + +--- + +Generated on: `Fri 25 Jul 2025 12:42:26 AEST` +~~~~ + +--- + +## Custom Parameters from command line + +You can define custom parameters in the frontmatter, and pass the value through command arguments. + +~~~~markdown +--- +output: "monthly_report_{{.b}}.md" +params: + b: + required: true + default: 2011-01 + usage: | + Required. + The begin time of report. + Examples: + 2025 + 2025-07 + 2025-07-15 + Jul + e: + required: true + default: 2011-02 + usage: | + Required. + The end time of report. + Same format as -b + f: + default: examples/ledger.j + usage: The ledger file to parse +--- + +# Finance Report from {{.b}} to {{.e}} + +## Previous status: + +{{ shell "hledger -f $f balancesheet -e $b" }} + +## Expenses: + +### Expense Summary by Category + +{{ shell "hledger -f $f bal expenses -b $b -e $e --depth 3 --sort amount --budget" }} + +## Net Income: + +{{shell "hledger -f $f income -b $b -e $e --monthly"}} + +## Ending balance: + +{{shell "hledger -f $f balancesheet -e $e"}} +~~~~ + +Run the template: + +**Note: you need to install `hledger` to run the example** + +``` +mdsh examples/monthly.md -b 2011-01 -e 2011-02 +``` + +The result: + +~~~~markdown +# Finance Report from 2011-01 to 2011-02 + +## Previous status: + +`Balance Sheet 2010-12-31 + + || 2010-12-31 +================================++============ + Assets || +--------------------------------++------------ + Assets:Checking || $-225.00 +--------------------------------++------------ + || $-225.00 +================================++============ + Liabilities || +--------------------------------++------------ + Liabilities:Mortgage:Principal || $-200.00 +--------------------------------++------------ + || $-200.00 +================================++============ + Net: || $-25.00` + +## Expenses: + +### Expense Summary by Category + +`Budget performance in 2011-01: + + || Jan +===============++============================== + Expenses || $5,629.00 + Expenses:Food || $109.00 [ 109% of $100.00] +---------------++------------------------------ + || $5,629.00 [5629% of $100.00]` + +`$5,500.00 Expenses:Auto + $109.00 Expenses:Food + $20.00 Expenses:Books +-------------------- + $5,629.00` + +## Net Income: + +`Income Statement 2011-01 + + || Jan +=========================++============ + Revenues || +-------------------------++------------ + Income:Salary || $2,000.00 +-------------------------++------------ + || $2,000.00 +=========================++============ + Expenses || +-------------------------++------------ + Expenses:Auto || $5,500.00 + Expenses:Books || $20.00 + Expenses:Food:Groceries || $109.00 +-------------------------++------------ + || $5,629.00 +=========================++============ + Net: || $-3,629.00` + +## Ending balance: + +`Balance Sheet 2011-01-31 + + || 2011-01-31 +================================++============ + Assets || +--------------------------------++------------ + Assets:Checking || $1,366.00 + Assets:Savings || $-5,200.00 +--------------------------------++------------ + || $-3,834.00 +================================++============ + Liabilities || +--------------------------------++------------ + Liabilities:MasterCard || $20.00 + Liabilities:Mortgage:Principal || $-200.00 +--------------------------------++------------ + || $-180.00 +================================++============ + Net: || $-3,654.00` +~~~~