README.md - zsh-banner - zsh-plugin to display ascii/ansi art on startup
HTML git clone https://git.drkhsh.at/zsh-banner.git
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
README.md (3450B)
---
1 ```
2 __ __
3 .-----.-----| |--.______| |--.---.-.-----.-----.-----.----.
4 |-- __|__ --| |______| _ | _ | | | -__| _|
5 |_____|_____|__|__| |_____|___._|__|__|__|__|_____|__|
6 ```
7
8 # zsh-banner
9
10 A zsh plugin to display ANSI/ASCII art on shell startup.
11
12 This is a simplified/slightly adapted and maintained fork of
13 [yuhonas/zsh-ansimotd](https://github.com/yuhonas/zsh-ansimotd).
14
15 ## Installation
16
17 ### Dependencies
18
19 * [zsh](https://www.zsh.org/)
20 * On non-GNU Linux systems (e.g. Alpine): gnu-iconv
21
22 #### Optional
23 * [shuf]( https://en.wikipedia.org/wiki/Shuf) which is part of gnu
24 [coreutils](https://formulae.brew.sh/formula/coreutils)
25 * [fd](https://github.com/sharkdp/fd) a modern `find` replacement, it will use
26 this preferentially if it's installed otherwise fallback to `find`.
27 * [pv](https://www.ivarch.com/programs/pv.shtml) a pipe viewer which can limit
28 the art rendering speed to emulate the feel of an old skool BBS.
29
30 ### Install using your favourite plugin manager or not
31
32 ```
33 # for zinit
34 zinit light drkhsh/zsh-banner
35
36 # for znap
37 znap source drkhsh/zsh-banner
38
39 # for antigen
40 antigen bundle drkhsh/zsh-banner
41
42 # for zplug
43 zplug "drkhsh/zsh-banner"
44
45 # manually
46 # Clone the repository and source it in your shell's rc file
47 ```
48
49 ### Getting some awesome ansi art to display
50
51 After installation you'll need to download some ansi art for it to randomly
52 display, I suggest a few places:
53
54 #### 16colo.rs
55
56 Head over to [16colo.rs](https://16colo.rs/) and if you find a year(s) you like
57 you can download everything from that year using their rsync mirror.
58
59 eg. to download everything from [1996](https://16colo.rs/year/1996/) to the
60 `ZSH_BANNER_DIR`:
61
62 ```
63 rsync -azvhP --include '*/' --include '*.ANS' --exclude '*' rsync://16colo.rs/pack/1996 "$ZSH_BANNER_DIR"
64 ```
65
66 #### artscene.textfiles.com
67
68 Find a pack you like at [artscene](http://artscene.textfiles.com/artpacks/) and
69 unpack it into the ansi motd config directory.
70
71 You can do this by copying any `.ans`, or `.asc` files containg ansi art into
72 your `ZSH_BANNER_DIR` directory which is derived from
73 `${XDG_CONFIG_HOME:-$HOME/.config}/ansimotd` (the plugin performs a recursive
74 search for art so any directory nesting is fine).
75
76 ### Configuration / Settings
77
78 The plugin exports the following useful variables to the session
79
80 * `ZSH_BANNER_DIR` - the full path to the config directory where the plugin
81 will search for ansi art
82 * `ZSH_BANNER_FILENAME` - the full file path to the last shown peice of ansi art,
83 if you want to do something with it, laud over it, delete it etc
84
85 There's also a handful of ENV variables you can use to configure the plugin
86 (these will need to be set prior to plugin instantiation).
87
88 #### The real BBS experience
89
90 To buffer the ansi art output at a fixed speed you can set the
91 `ZSH_BANNER_RATE_LIMIT_OUTPUT` ENV variable.
92
93 eg. to limit the ansi art rendering rate to a data rate of 8k:
94
95 ```
96 export ZSH_BANNER_RATE_LIMIT_OUTPUT="8k"
97 ```
98
99 #### Small screens
100
101 If you happen to be running on a small fixed screen perhaps on something like
102 [termux](https://termux.dev/en/) you can set the following environemnt variable
103 to truncate the art to screen width:
104
105 ```
106 export ZSH_BANNER_DISABLE_LINE_WRAPPING=1
107 ```
108
109 ### Note
110
111 Art to be displayed is assumed to use the
112 [Code Page 437]( https://en.wikipedia.org/wiki/Code_page_437 ) character set.
113
114
115 ### License
116
117 This project is licensed under the [MIT](./LICENSE) license.
118