A Babashka 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.
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 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.
$ brew install eval/brew/venster
- babashka
- bbin
- glow
$ bbin install https://github.com/eval/venster/releases/download/stable/venster-bb.jar --as venster
- Create a section '## Links' (any depth is ok) in the project's
README.md
- Add links
Available values for Selmer filters:
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 viagit config --global github.user eval
- env-var
gitlab-user
Determined via...- env-var
VENSTER_GITLAB_USER
. - git config gitlab.user
Add viagit config --global gitlab.user eval
- env-var
readme-folder
Folder whereREADME.md
is located. Allows for pointing to project-files,
e.g.{{ readme-folder }}/.github/workflows/ci.yml
.
- Invoking
venster
in any subfolder of the project will now render the links.
Example Links-section in a README.md
(see also the Links-section of this README):
## Links
- [Repository](https://github.com/eval/venster)
### Pull Requests
<!-- This comment won't be rendered.
Pull Requests across multiple repositories assigned to user with fallback in case there's no github-user -->
- [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 }})
# from $PROJECT_ROOT
$ bb -m eval.venster some args
# bbin install
$ bbin install . --as venster-dev
# ...then in another project
$ venster-dev
- ...
- Project
- [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 current branch](https://github.com/eval/venster/actions?query=branch%3A{{ current-branch | default:"main" }})
- [Release workflow ]({{ readme-folder }}/.github/workflows/release.yml)
Clojure solves the problem that you don't know you have. -- Rich Hickey
Copyright (c) 2023 Gert Goet, ThinkCreate. Distributed under the MIT license. See LICENSE.