https://github.com/eval/venster
Render the README's Links-section in the terminal
https://github.com/eval/venster
babashka clojure glow
Last synced: 3 months ago
JSON representation
Render the README's Links-section in the terminal
- Host: GitHub
- URL: https://github.com/eval/venster
- Owner: eval
- License: mit
- Created: 2023-10-04T07:59:46.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-10-06T09:32:19.000Z (over 1 year ago)
- Last Synced: 2025-01-13T01:44:30.037Z (5 months ago)
- Topics: babashka, clojure, glow
- Language: Clojure
- Homepage:
- Size: 23.4 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Venster
A [Babashka](https://babashka.org/) CLI to render the Links-section of a README.md in your terminal to make them conveniently clickable. Templating is supported to allow for contextualized links.
## Rationale
I started experimenting with having a Links-section in READMEs to quickly jump to places while developing: e.g. the project on GitHub, the issue list, the notifications, anything assigned to me but also any link to staging/production front- and backends.
A quick experiment with an awk-script, [glow](https://github.com/charmbracelet/glow) as a pager and iTerm, which makes urls easily clickable, showed it was indeed something useful that removed friction.
The current version allows for placeholders, i.e. making links more contextualized as they can contain the current branch, env-vars and one's git(hub|lab) handle which makes it more suitable to use with a team.
## Install
### homebrew
``` shell
$ brew install eval/brew/venster
```
### bbin
#### Prerequisites
* babashka
* bbin
* glow
#### Install
``` shell
$ bbin install https://github.com/eval/venster/releases/download/stable/venster-bb.jar --as venster
```
## Usage
1. Create a section '## Links' (any depth is ok) in the project's `README.md`
1. Add links
Available values for [Selmer filters](https://github.com/yogthos/Selmer?tab=readme-ov-file#built-in-filters-1):
- `env`
e.g. `file:/{{ env.HOME }}/.vimrc`. Which is a link that your terminal can let you open with an editor.
- `current-branch`
Current git branch, e.g. `https://github.com/eval/venster/actions?query=branch%3A{{ current-branch | default:"main" }}`.
- `github-user`
e.g. `https://github.com/eval/venster/issues/assigned/{{ github-user }}`, or
to have a fallback when the value is not present: `https://github.com/eval/venster/issues{% if github-user %}/assigned/{{ github-user }}{% endif %}`.
Determined via...
- env-var `VENSTER_GITHUB_USER`.
- git config github.user
Add via `git config --global github.user eval`
- `gitlab-user`
Determined via...
- env-var `VENSTER_GITLAB_USER`.
- git config gitlab.user
Add via `git config --global gitlab.user eval`
- `readme-folder`
Folder where `README.md` is located. Allows for pointing to project-files,
e.g. `{{ readme-folder }}/.github/workflows/ci.yml`.
1. Invoking `venster` in any subfolder of the project will now render the links.
### Example
Example Links-section in a `README.md` (see also the Links-section of this README):
```
## Links
- [Repository](https://github.com/eval/venster)
### Pull Requests
- [My PRs](https://github.com/pulls?q=is%3Apr+archived%3Afalse+repo%3Aeval%2Fmalli-select+repo%3Aeval%2Fdeps-try+is%3Aopen{% if github-user %}+assignee%3A{{ github-user }}+{% endif %})
### Builds
- [Builds current branch](https://github.com/eval/venster/actions?query=branch%3A{{ current-branch | default:"main" }})
- [Release workflow ]({{ readme-folder }}/.github/workflows/release.yml)
### API Docs
- [Ruby docs](https://docs.ruby-lang.org/en/{{ env.RUBY_VERSION|drop-last:2|join }})
```
### Dev
``` shell
# from $PROJECT_ROOT
$ bb -m eval.venster some args
# bbin install
$ bbin install . --as venster-dev
# ...then in another project
$ venster-dev
```
## Wishlist
- ...
## Links
- [Project ](https://github.com/eval/venster)
- [Current branch ](https://github.com/eval/venster/tree/{{ current-branch | default:"main" }})
- [My Issues ](https://github.com/eval/venster/issues{% if github-user %}/assigned/{{ github-user }}{% endif %})
- [My PRs ](https://github.com/eval/venster/pulls{% if github-user %}/assigned/{{ github-user }}{% endif %})
### Builds
- [Builds current branch](https://github.com/eval/venster/actions?query=branch%3A{{ current-branch | default:"main" }})
- [Release workflow ]({{ readme-folder }}/.github/workflows/release.yml)
### Releasing
- [Stable](https://github.com/eval/venster/releases/tag/stable)
- [Unstable](https://github.com/eval/venster/releases/tag/unstable)
- [Homebrew repository ](https://github.com/eval/homebrew-brew)
> Clojure solves the problem that you don't know you have. -- Rich Hickey
## License
Copyright (c) 2023 Gert Goet, ThinkCreate. Distributed under the MIT license. See [LICENSE](./LICENSE).