https://github.com/purarue/pmark
A hacky, markdown pre-processor/generator
https://github.com/purarue/pmark
cli markdown markdown-generator scripting
Last synced: 4 months ago
JSON representation
A hacky, markdown pre-processor/generator
- Host: GitHub
- URL: https://github.com/purarue/pmark
- Owner: purarue
- License: apache-2.0
- Created: 2020-08-05T20:11:30.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-11-12T04:11:30.000Z (over 1 year ago)
- Last Synced: 2024-11-12T04:29:50.798Z (over 1 year ago)
- Topics: cli, markdown, markdown-generator, scripting
- Language: Perl
- Homepage:
- Size: 47.9 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# pmark
A hacky, markdown pre-processor.
Uses code blocks to generate markdown, from within the markdown itself.
This allows you to specify any sort of script to execute as a code block, whose contents then get replaced by the output of the script.
As an example, in a file `P_README.md`:
## README
Description of project
```
>>>PMARK
#!/bin/sh
printf 'This was last edited by %s on *%s*\n' "$(whoami)" "$(date)"
```
Running `pmark ./P_README.md` would generate the file `README.md`, with contents:
## README
Description of project
This was last edited by username on *Wed 05 Aug 2020 05:44:55 AM PDT*
---
Say you want a markdown file to act as an index for other directories in the folder, to create a table of contents of sort.
Directory Contents:
```
.
├── 01
│ └── README.md
├── 02
│ └── README.md
├── 03
│ └── README.md
└── P_TABLE_OF_CONTENTS.md
```
`P_TABLE_OF_CONTENTS.md`:
Book Contents:
```
>>>PMARK
#!/usr/bin/env python3
import os
for path in os.listdir():
if os.path.isdir(path):
# create markdown which links to that chapter
print("* [Chapter {}]({})".format(path, path + '/README.md')
```
For more info, visit ...
That would generate the following markdown:
`TABLE_OF_CONTENTS.md`
Book Contents:
* [Chapter 01](01/README.md)
* [Chapter 02](02/README.md)
* [Chapter 03](03/README.md)
For more info, visit ...
There's no restriction on the language, this creates the corresponding script file (with a random name, like `/CT1PIRQX5-pmark`) and executes it from the markdown files' directory.
---
This sets two environment variables that are accessible from within the script:
- `RUN_FROM`: The directory `pmark` was executed in.
- `IN_DIR`: The directory this markdown file is in.
---
If you wanted to run this against all files which contain `pmark` blocks recursively, can combine this with the `find` command:
`find . -name 'P_*.md' -exec pmark {} +`
Or, with [`fd`](https://github.com/sharkdp/fd):
`fd 'P_*.md' -X pmark`
If no files are provided, this searches for files matching `P_*.md` in the current directory.
---
I'll often use this in Github `README`s, especially for new projects, as while I'm developing tools/libraries it keeps my `README` up to date with the right flags/example output, e.g.,:
```
>>>PMARK
perl -E 'print "`"x3, "\n"'
make
./mytool -h
make clean
perl -E 'print "`"x3, "\n"'
```
In my `.git/hooks/pre-commit` I have, so it runs right before I commit:
```
find . -name 'P_*.md' -exec pmark {} \+
```
For examples see [here](https://github.com/purarue/ttally/blob/26f3b32ed6085efea965185c79e831a0ab033770/P_README.md) or [here](https://github.com/purarue/plaintext-playlist/blob/8b053fa45a19ccb4e82f4d47cfe58802a94ff252/P_README.md)
As a more complex example, I use this for my blog, see [my blog index](https://github.com/purarue/exobrain/tree/24a5440fe57943c531231fd24f4e2bd07856ccc2/sitemap).
### Installation
Or [`basher`](https://github.com/basherpm/basher):
```
basher install purarue/pmark
```
### Specification
- Expects the filename to start with `P_`, the output filename is the rest of the filename excluding the `P_` prefix.
- The markdown block must start with `>>>PMARK`, all other code blocks are ignored.
- Like markdown itself, nested code blocks are not allowed. If you want to generate a markdown codeblock using code, see [`examples/P_SHELL.md`](examples/P_SHELL.md) for a workaround.