mirror of
https://github.com/charmbracelet/gum
synced 2024-05-29 11:52:35 +02:00
docs: table of contents like navigation
This commit is contained in:
parent
d6b895b7f1
commit
56ad131ed4
66
README.md
66
README.md
|
@ -12,29 +12,20 @@ Gum
|
||||||
Gum helps you write glamorous bash scripts by providing a collection of
|
Gum helps you write glamorous bash scripts by providing a collection of
|
||||||
beautiful and highly configurable ready-to-use utilities.
|
beautiful and highly configurable ready-to-use utilities.
|
||||||
|
|
||||||
Let's build a `git commit` helper for your dotfiles.
|
Build a useful `git commit` helper for your dotfiles with a couple lines of `bash`:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
TYPE=$(gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert")
|
||||||
|
SCOPE=$(gum input --placeholder "scope")
|
||||||
|
[[ -n "$SCOPE" ]] && SCOPE="($SCOPE)"
|
||||||
|
SUMMARY=$(gum input --width 50 --value "$TYPE$SCOPE: " --placeholder "Summary of this change")
|
||||||
|
DESCRIPTION=$(gum write --width 80 --placeholder "Details of this change")
|
||||||
|
gum spin --title "Commiting..." -- git commit -m "$SUMMARY" -m "$DESCRIPTION"
|
||||||
|
```
|
||||||
|
|
||||||
<img src="https://stuff.charm.sh/gum/commit.gif" width="600" alt="Running the ./examples/commit.sh script to commit to git">
|
<img src="https://stuff.charm.sh/gum/commit.gif" width="600" alt="Running the ./examples/commit.sh script to commit to git">
|
||||||
|
|
||||||
```bash
|
|
||||||
# Get the commit type by asking the user to choose an option from the
|
|
||||||
# conventional commit Specification and store it in $TYPE.
|
|
||||||
TYPE=$(gum choose "fix" "feat" "docs" "style" "refactor" "test" "chore" "revert")
|
|
||||||
|
|
||||||
# Optionally, provide a scope by prompting for input.
|
|
||||||
SCOPE=$(gum input --placeholder "scope")
|
|
||||||
|
|
||||||
# Wrap the scope in parentheses if non-empty.
|
|
||||||
[[ -n "$SCOPE" ]] && SCOPE="($SCOPE)"
|
|
||||||
|
|
||||||
# Prompt for commit message summary.
|
|
||||||
# We pre-populate the value with the type and scope of the commit message in #
|
|
||||||
case the user changes their mind.
|
|
||||||
SUMMARY=$(gum input --value "$TYPE$SCOPE: " --placeholder "Summary of this change")
|
|
||||||
|
|
||||||
# Prompt for a multi-line description of these changes
|
|
||||||
DESCRIPTION=$(gum write --placeholder "Details of this change")
|
|
||||||
```
|
|
||||||
|
|
||||||
Or, a simplified version (one-liner for your dotfiles as a shell aliases):
|
Or, a simplified version (one-liner for your dotfiles as a shell aliases):
|
||||||
|
|
||||||
|
@ -42,6 +33,25 @@ Or, a simplified version (one-liner for your dotfiles as a shell aliases):
|
||||||
git commit -m "$(gum input)" -m "$(gum write)"
|
git commit -m "$(gum input)" -m "$(gum write)"
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## Components
|
||||||
|
|
||||||
|
1. [Interaction](#Interaction)
|
||||||
|
* [Input](#input): Prompt for some input
|
||||||
|
* [Write](#write): Prompt for multi-line input
|
||||||
|
* [Filter](#filter): Fuzzy find from a list of options
|
||||||
|
* [Choose](#choose): Prompt user to choose (an) option(s) from a list of choices
|
||||||
|
* [Progress](#progress): Display a progress bar to the user
|
||||||
|
* [Spin](#spin): Show a spinner while doing some work in the background
|
||||||
|
2. [Styling](#styling)
|
||||||
|
* [Style](#style): Apply CSS-like styling to strings
|
||||||
|
3. [Layout](#Layout)
|
||||||
|
* [Join](#join): Join text horizontally or vertically for building layouts
|
||||||
|
4. [Format](#Format)
|
||||||
|
* [Markdown](#markdown): Render markdown
|
||||||
|
* [Code](#code): Render syntax-highlighted code
|
||||||
|
* [Template](#template): Render styles applied from a template string
|
||||||
|
* [Emoji](#emoji): Render emojis from `:emoji:` syntax
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
Use a package manager:
|
Use a package manager:
|
||||||
|
@ -157,7 +167,7 @@ gum progress --increment 0.1 --interval 1s
|
||||||
|
|
||||||
<img src="https://stuff.charm.sh/gum/progress.gif" width="600" alt="Shell running gum progress">
|
<img src="https://stuff.charm.sh/gum/progress.gif" width="600" alt="Shell running gum progress">
|
||||||
|
|
||||||
#### Spinners
|
#### Spin
|
||||||
|
|
||||||
Display a spinner while taking some running action. We specify the command to
|
Display a spinner while taking some running action. We specify the command to
|
||||||
run while showing the spinner, the spinner will automatically stop after the
|
run while showing the spinner, the spinner will automatically stop after the
|
||||||
|
@ -169,9 +179,10 @@ gum spin --spinner dot --title "Buying Bubble Gum..." -- sleep 5
|
||||||
|
|
||||||
<img src="https://stuff.charm.sh/gum/spin.gif?cache=1" width="600" alt="Shell running gum spin while sleeping for 5 seconds">
|
<img src="https://stuff.charm.sh/gum/spin.gif?cache=1" width="600" alt="Shell running gum spin while sleeping for 5 seconds">
|
||||||
|
|
||||||
## Styling and Layout
|
## Styling
|
||||||
|
|
||||||
#### Style
|
#### Style
|
||||||
|
|
||||||
Pretty print any string with any layout with one command.
|
Pretty print any string with any layout with one command.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
@ -183,6 +194,8 @@ gum style \
|
||||||
|
|
||||||
<img src="https://stuff.charm.sh/gum/style.png?cache=1" width="600" alt="Bubble Gum, So sweet and so fresh!">
|
<img src="https://stuff.charm.sh/gum/style.png?cache=1" width="600" alt="Bubble Gum, So sweet and so fresh!">
|
||||||
|
|
||||||
|
## Layout
|
||||||
|
|
||||||
#### Join
|
#### Join
|
||||||
|
|
||||||
Combine text vertically or horizontally with a single command, use this command
|
Combine text vertically or horizontally with a single command, use this command
|
||||||
|
@ -204,7 +217,9 @@ gum join --align center --vertical "$I_LOVE" "$BUBBLE_GUM"
|
||||||
|
|
||||||
<img src="https://stuff.charm.sh/gum/join.png" width="600" alt="I LOVE Bubble Gum written out in four boxes with double borders around them.">
|
<img src="https://stuff.charm.sh/gum/join.png" width="600" alt="I LOVE Bubble Gum written out in four boxes with double borders around them.">
|
||||||
|
|
||||||
#### Format
|
## Format
|
||||||
|
|
||||||
|
#### Markdown
|
||||||
|
|
||||||
Format allows you to take some text and stylize it. `gum format` can parse
|
Format allows you to take some text and stylize it. `gum format` can parse
|
||||||
markdown, code, template strings, and emoji strings.
|
markdown, code, template strings, and emoji strings.
|
||||||
|
@ -218,6 +233,8 @@ echo "# Gum Formats\n- Markdown\n- Code\n- Template\n- Emoji" | gum format
|
||||||
|
|
||||||
<img src="https://stuff.charm.sh/gum/format-markdown.png" width="250" alt="Format markdown displaying a markdown list with content of different possible formats">
|
<img src="https://stuff.charm.sh/gum/format-markdown.png" width="250" alt="Format markdown displaying a markdown list with content of different possible formats">
|
||||||
|
|
||||||
|
#### Code
|
||||||
|
|
||||||
Apply syntax highlighting to code with `gum format -t code`:
|
Apply syntax highlighting to code with `gum format -t code`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
@ -226,6 +243,8 @@ cat main.go | gum format -t code
|
||||||
|
|
||||||
<img src="https://stuff.charm.sh/gum/format-code.png" width="400" alt="Format code command displaying a simple Hello, world! Go program with syntax highlighting.">
|
<img src="https://stuff.charm.sh/gum/format-code.png" width="400" alt="Format code command displaying a simple Hello, world! Go program with syntax highlighting.">
|
||||||
|
|
||||||
|
#### Template
|
||||||
|
|
||||||
Render a template string with `gum format -t template`:
|
Render a template string with `gum format -t template`:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
@ -237,6 +256,7 @@ echo '{{ Bold "Tasty" }} {{ Italic "Bubble" }} {{ Color "99" "0" " Gum " }}' \
|
||||||
|
|
||||||
Render some emojis with `:emoji:` syntax with `gum format -t emoji`.
|
Render some emojis with `:emoji:` syntax with `gum format -t emoji`.
|
||||||
|
|
||||||
|
#### Emoji
|
||||||
```bash
|
```bash
|
||||||
echo 'I :heart: Bubble Gum :candy:' | gum format -t emoji
|
echo 'I :heart: Bubble Gum :candy:' | gum format -t emoji
|
||||||
```
|
```
|
||||||
|
|
Loading…
Reference in a new issue