Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/tzador/makedown
Organise your shell scripts within executable markdown files
https://github.com/tzador/makedown
cli makefile markdown scripts
Last synced: 11 days ago
JSON representation
Organise your shell scripts within executable markdown files
- Host: GitHub
- URL: https://github.com/tzador/makedown
- Owner: tzador
- License: mit
- Created: 2024-10-13T01:42:34.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2024-10-18T19:03:11.000Z (25 days ago)
- Last Synced: 2024-10-21T00:11:39.551Z (23 days ago)
- Topics: cli, makefile, markdown, scripts
- Language: Python
- Homepage:
- Size: 439 KB
- Stars: 233
- Watchers: 5
- Forks: 9
- Open Issues: 23
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# [makedown]() - A Markdown powered Makefile alternative
`makedown` (aka Makefile + Markdown) is motivated by developers need to define
multiple scripts in one file next to their documentation, and have a handy way
to run them from terminal.
`Makefile`s are great for this, but are lucking some of the
[`makedown`](https://github.com/tzador/makedown) features, such as syntax
highlighting, hierarchical scanning of .md files with embedded documentation.
There are also `package.json` scripts in `node.js` world, but users are forced
to write script commands in one line.
It is implemented in Python for portability reasons, since most Unix-like
systems already have a Python interpreter installed.
Here is [DEMO.md](./DEMO.md) file with examples of usage.
---
This is a fresh project still under active development.
Feel free to open and [issue](https://github.com/tzador/makedown/issues) or
[PR](https://github.com/tzador/makedown/pulls).
We also have have a [Discord](https://discord.gg/Gcr9H897zD) server for quick
discussions and sharing ideas or feedback.
---
## Key Features
- **Executable Markdown Scripting**: Use markdown files (.md) to organize
commands and their documentation.
- **Multilingual Execution**: Supports `zsh`, `bash`, `javascript`, `python` and
**infinitely** many more, using custom hashbangs.
- **Syntax Highlighting**: Leverages markdown code blocks for readability.
---
## Install
```bash
pip install makedown
```
## Use
Define commands in a `.md` file:
````markdown
# my_scripts.md
Here are a few examples of commands:
## [hello]() Prints "hello" using bash
```bash
echo "hello"
```
## [world]() Prints "world" using python
This is a more detailed description of the command.
```python
#!/usr/bin/env python
print("world")
```
````
To run commands in a markdown file, execute `makedown` from the same directory
or any subdirectory:
```bash
makedown hello
```
A shorter version is also available:
```bash
m world
```
To see all the available commands with their short descriptions, use one of the
following:
```bash
makedown --help
```
or just run it without any arguments:
```bash
m
```
To get more details about a specific command, use:
```bash
makedown world --help
```
## Upgrade
```bash
pip install --upgrade makedown
```
## Uninstall
```bash
pip uninstall makedown
```