[HN Gopher] Show HN: A Markdown-based alternative to package.jso...
___________________________________________________________________
Show HN: A Markdown-based alternative to package.json scripts and
makefiles
`x.md` allows you to organise your cli scripts in one or several
markdown files, by mix and matching different scripting languages
for various commands, such as zsh/bash/sh, python or javascript.
Handy for replacing one-line-based `package.json` scripts or
`Makefile`s. One can also write documentation and explanations to
various commands in same `x.md` markdown file. ZSH autocompletions
are also working, suggesting you the most relevant available
commands from your `x.md` files. Most editors highlight correctly
most languages in the markdown code blocks, even when you use
several scripting languages. Provided the following example (x.md
file in the root of your project), one can run in a terminal:
$ x weather-tomorrow or # x generate-
password --- An example of x.md file ---
# hello Prints "Hello" to `stdout` using Zsh.
```zsh echo "Hello" ``` # world
Just prints "World" to `stdout` using JavaScript.
```js console.log("World"); ``` #
weather-tomorrow Prints the weather for tomorrow to
`stdout` using Zsh. ```zsh curl
wttr.in/tomorrow ``` # generate-password
Prints a random password to `stdout` using Python.
```python import random import string
length = 16 characters = string.ascii_letters +
string.digits + string.punctuation password =
''.join(random.choice(characters) for _ in range(length))
print(password) ``` --- end of x.md ---
The syntax is simple, each command is a level 1 header followed by
optional documentation in markdown notation, and followed by
annotated (which interpreter to use) code block. One can type
`--help` after `x my-command` to print out the help associated with
that command. It is possible to have multiple files with scripts,
just put them in the `x` folder with `.md` extension. Would be
very grateful for any suggestions or other feedback. Thank you.
Author : timz
Score : 40 points
Date : 2024-10-13 05:15 UTC (2 days ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| mutant wrote:
| 404
| timz wrote:
| should be working now https://github.com/tzador/x.md
| az09mugen wrote:
| That's an interesting idea you had, it makes me think of a mix
| between a jupyter notebook and a makefile, sort of, based on md
| files. I like the concept, but I need to test it to see if it
| fits my needs. Just a question about python and zsh, do they need
| to be pre-installed in your OS and accessible from PATH, that's
| it ?
| cobalt60 wrote:
| ansible for markdown?
| porridgeraisin wrote:
| It'll be nice if you could make it level 2 headers. Reason: if we
| want to make it html to display as a webpage, we won't end up
| with multiple H1s, and we can have a H1 for like the name of the
| app or something.
| timz wrote:
| Great suggestion. On it
| zahlman wrote:
| >One can type `--help` after `x my-command` to print out the help
| associated with that command.
|
| I assume that there is no support for the scripts having their
| own command-line arguments? Or how do you disambiguate?
|
| Anyway, this seems like an interesting demo, but it's hard to
| imagine the use case.
| timz wrote:
| When --help is provided, the help text from x.md is printed.
| Otherwise all the command line parameters are passed to the
| actual script that implements the command.
| timz wrote:
| published 0.3 version pnpm install -g @tzador/x.md
|
| - better --help messages with or without command - ## level 2
| headers are used - the temp file is created in current folder,
| like that importing npm modules from current project works
| djbusby wrote:
| X is kinda overloaded. Maybe "makedown"? Or something?
|
| I just do mine in bash (make.sh) and it runs scripts from make.d/
| which are in whatever (python, js bash, PHP)
| nunobrito wrote:
| Makedown is a good name. +1 vote from me (in case it counts)
| timz wrote:
| Love the makedown name, renaming.. As for a short name
| available in terminal, we can add alias m="makedown" as part
| of zsh completion script. Both: $ makedown deploy-to-
| production and $ m deploy-to-production --help will work
|
| Aditionally we can generate html out of the, now
| `makedown.md`, right in the tool: $ makedown --html
| makedown.html or $ m --pdf makedown.pdf
| efilife wrote:
| Remember to change it in the readme as well
| nunobrito wrote:
| Plus points for being a readable format that can be displayed
| great on HTML or PDF.
|
| At the same time easy to edit and easy to enhance with different
| build languages as needed.
| snake_case wrote:
| It's great to see more tools taking advantage of the markdown
| syntax.
|
| I'm the creator of Mask[0], a very similar tool built with Rust.
| I was originally inspired by Maid[1], which is an older take on
| this idea built with Node and no longer maintained I believe.
|
| I see this is based on Node as well, and I appreciate that it
| currently has zero dependencies. Nice work!
|
| [0]: https://github.com/jacobdeichert/mask
|
| [1]: https://github.com/egoist/maid
| emareg wrote:
| Nice idea! Can I reuse variables that I have defined in e.g. a JS
| code block in another ZSH code block and vice versa?
___________________________________________________________________
(page generated 2024-10-15 23:01 UTC)