Skip to content
/ venster Public

Render the README's Links-section in the terminal

License

Notifications You must be signed in to change notification settings

eval/venster

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

24 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Venster

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.

Screenshot 2023-10-04 at 14 26 22

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 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

$ brew install eval/brew/venster

bbin

Prerequisites

  • babashka
  • bbin
  • glow

Install

$ 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
  2. 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 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.
  3. 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

<!-- 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 }})

Dev

# from $PROJECT_ROOT
$ bb -m eval.venster some args

# bbin install
$ bbin install . --as venster-dev

# ...then in another project
$ venster-dev

Wishlist

  • ...

Links

Builds

Releasing

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.