psi-jack/zimfw
1
0
Fork 0
mirror of synced 2024-12-25 23:43:20 -05:00
Code Issues Releases Wiki Activity

Update README.md with badges, ToC, sample rc files

Browse source 
Closes #453

Co-authored-by: Eric Nielsen <eric@amalgamar.com.br>
This commit is contained in:
RayZ0rr 2022-03-04 07:49:40 +05:30 committed by GitHub
parent 4fe7c66e07
commit 97133502fd
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 139 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

185
README.md
View file

@ -1,3 +1,13 @@
<p align="center">
<a href="https://github.com/zimfw/zimfw/releases"><img src="https://img.shields.io/github/v/release/zimfw/zimfw"></a>
<a href="https://github.com/zimfw/zimfw/issues"><img src="https://img.shields.io/github/issues/zimfw/zimfw.svg"></a>
<a href="https://github.com/zimfw/zimfw/network/members"><img src="https://img.shields.io/github/forks/zimfw/zimfw.svg"></a>
<a href="https://github.com/zimfw/zimfw/stargazers"><img src="https://img.shields.io/github/stars/zimfw/zimfw.svg"></a>
<a href="https://github.com/zimfw/zimfw/releases"><img src="https://img.shields.io/github/downloads/zimfw/zimfw/total.svg"></a>
<a href="https://github.com/zimfw/zimfw/discussions"><img src="https://img.shields.io/badge/forum-online-green.svg"></a>
<a href="https://github.com/zimfw/zimfw/blob/master/LICENSE"><img alt="GitHub" src="https://img.shields.io/github/license/zimfw/zimfw"></a>
</p>
<div align="center">
<a href="https://github.com/zimfw/zimfw">
<img width="600" src="https://zimfw.github.io/images/zimfw-banner@2.jpg">
@ -6,74 +16,157 @@
What is Zim?
------------
Zim is a Zsh configuration framework with [blazing speed] and modular extensions.
Zim is a Zsh configuration framework that bundles a [plugin manager](#usage),
useful [modules], and a wide variety of [themes], without compromising on [speed].
Zim bundles useful [modules], a wide variety of [themes], and plenty of
customizability without compromising on speed.
Check how Zim compares to other frameworks and plugin managers:
What does Zim offer?
--------------------
Below is a brief showcase of Zim's features.
### Speed
<a href="https://github.com/zimfw/zimfw/wiki/Speed">
<img src="https://zimfw.github.io/images/results.svg">
</a>
For more details, see [this wiki entry][blazing speed].
### Modules
Zim has many [modules available][modules]. Enable as many or as few as you'd like.
### Themes
To preview some of the available themes, check the [themes page][themes].
### Degit
Install modules without requiring `git` using our degit tool. It's faster and
lighter than `git`. See the [zmodule](#zmodule-usage) usage below.
Table of Contents
-----------------
* [Installation](#installation)
* [Automatic installation](#automatic-installation)
* [Manual installation](#manual-installation)
* [Set up `~/.zshrc`](#set-up-zshrc)
* [Create `~/.zimrc`](#create-zimrc)
* [Usage](#usage)
* [`zmodule`](#zmodule)
* [`zimfw`](#zimfw)
* [Settings](#settings)
* [Uninstalling](#uninstalling)
Installation
------------
Installing Zim is easy:
Installing Zim is easy. You can choose either the automatic or manual method below:
* With curl:
### Automatic installation
This will install a predefined set of modules and a theme for you.
* With `curl`:
curl -fsSL https://raw.githubusercontent.com/zimfw/install/master/install.zsh | zsh
* With wget:
* With `wget`:
wget -nv -O - https://raw.githubusercontent.com/zimfw/install/master/install.zsh | zsh
Open a new terminal and you're done. Enjoy your Zsh IMproved! Take some time to
tweak your `~/.zshrc` file, and to also check the available [modules] and [themes]
you can add to your `~/.zimrc`.
<details>
<summary>Prefer to install manually?</summary>
Restart your terminal and you're done. Enjoy your Zsh IMproved! Take some time
to tweak your [`~/.zshrc`](#set-up-zshrc) file, and to also check the available
[modules] and [themes] you can add to your [`~/.zimrc`](#create-zimrc).
### Manual installation
1. Set Zsh as the default shell:
1. Set Zsh as the default shell, if you haven't done so already:
```zsh
chsh -s $(which zsh)
````
2. Prepend the lines in the following templates to the respective dot files:
2. [Set up your `~/.zshrc` file](#set-up-zshrc)
* [~/.zshrc](https://raw.githubusercontent.com/zimfw/install/master/src/templates/zshrc)
* [~/.zimrc](https://raw.githubusercontent.com/zimfw/install/master/src/templates/zimrc)
3. [Create your `~/.zimrc` file](#create-zimrc)
3. Restart your terminal to automatically install the `zimfw` command line utility,
install the modules defined in `~/.zimrc`, and build the initialization scripts.
</details>
4. Restart your terminal and you're done. Enjoy your Zsh IMproved!
#### Set up `~/.zshrc`
Add the lines below to your `~/.zshrc` file, in the following order:
1. To use our `degit` tool by default to install modules:
```zsh
zstyle ':zim:zmodule' use 'degit'
````
This is optional, and only required if you don't have `git` installed (yes,
Zim works even without `git`!)
2. To set where the directory used by Zim will be located:
```zsh
ZIM_HOME=~/.zim
```
The value of `ZIM_HOME` can be any directory your user has write access to.
You can even set it to a cache directory like `${XDG_CACHE_HOME}/zim` or
`~/.cache/zim` if you also include the step below, that automatically
downloads the `zimfw` plugin manager.
3. To automatically download the `zimfw` plugin manager if missing:
```zsh
# Download zimfw plugin manager if missing.
if [[ ! -e ${ZIM_HOME}/zimfw.zsh ]]; then
curl -fsSL --create-dirs -o ${ZIM_HOME}/zimfw.zsh \
https://github.com/zimfw/zimfw/releases/latest/download/zimfw.zsh
fi
```
Or if you use `wget` instead of `curl`:
```zsh
# Download zimfw plugin manager if missing.
if [[ ! -e ${ZIM_HOME}/zimfw.zsh ]]; then
mkdir -p ${ZIM_HOME} && wget -nv -O ${ZIM_HOME}/zimfw.zsh \
https://github.com/zimfw/zimfw/releases/latest/download/zimfw.zsh
fi
```
This is optional. If you choose to not include this step, you should manually
download the `zimfw.zsh` script once and keep it at `${ZIM_HOME}`.
4. To automatically install missing modules and update the initialization script
if missing or outdated:
```zsh
# Install missing modules, and update ${ZIM_HOME}/init.zsh if missing or outdated.
if [[ ! ${ZIM_HOME}/init.zsh -nt ${ZDOTDIR:-${HOME}}/.zimrc ]]; then
source ${ZIM_HOME}/zimfw.zsh init -q
fi
```
This step is optional, but highly recommended. If you choose to not include
it, you must remember to manually run `zimfw install` every time after you
update your [`~/.zimrc`](#create-zimrc) file.
5. To source the initialization script, that initializes your modules:
```zsh
# Initialize modules.
source ${ZIM_HOME}/init.zsh
```
#### Create `~/.zimrc`
You must create your `.zimrc` file at `~/.zimrc`, if the `ZDOTDIR` environment
variable is not defined. Otherwise, it must be at `${ZDOTDIR}/.zimrc`. It's
referred to as `~/.zimrc` in the documentation for the sake of simplicity.
You can start with just:
```zsh
zmodule zsh-users/zsh-syntax-highlighting
zmodule zsh-users/zsh-autosuggestions
```
Or, if you also want to use completions:
```zsh
zmodule zsh-users/zsh-completions --fpath src
zmodule completion
zmodule zsh-users/zsh-syntax-highlighting
zmodule zsh-users/zsh-autosuggestions
```
The [completion] module calls `compinit` for you. You should remove any
`compinit` calls from your `~/.zshrc` when you use this module. The modules will
be initialized in the order they are defined, and [completion] must be
initialized after all modules that add completion definitions, so it comes after
[zsh-users/zsh-completions].
See the [`zmodule` usage](#zmodule) below for more examples on how to use it to
define the modules you want to use.
Usage
-----
The `zimfw` plugin manager builds an initialization script, at `${ZIM_HOME}/init.zsh`,
that initializes the modules you defined in your `~/.zimrc` file.
Add `zmodule` calls to your `~/.zimrc` file to define the modules to be
initialized, then run `zimfw install` to install them.
The `~/.zimrc` file must contain a `zmodule` call for each module you want to
use. The modules will be initialized in the order they are defined.
The `~/.zimrc` file is not sourced during Zsh startup, and it's only used to
configure the `zimfw` plugin manager.
The [examples of `~/.zimrc` files](#create-zimrc) above.
### zmodule
@ -146,17 +239,16 @@ Initialization options:
### zimfw
The command line utility for Zim:
The Zim plugin manager:
* Added new modules to `~/.zimrc`? Run `zimfw install`.
* Removed modules from `~/.zimrc`? Run `zimfw uninstall`.
* Want to update your modules to their latest revisions? Run `zimfw update`.
* Want to upgrade `zimfw` to its latest version? Run `zimfw upgrade`.
* For more information about the `zimfw` utility, run `zimfw help`.
* For more information about the `zimfw` plugin manager, run `zimfw help`.
Settings
--------
Modules are installed using `git` by default. If you don't have `git`
installed, or if you want to take advantage of our degit tool for faster and
lighter module installations, you can set degit as the default tool with:
@ -170,11 +262,12 @@ This can be disabled with:
Uninstalling
------------
The best way to remove Zim is to manually delete `~/.zim`, `~/.zimrc`, and
remove the initialization lines from your `~/.zshenv`, `~/.zshrc` and `~/.zlogin`.
[blazing speed]: https://github.com/zimfw/zimfw/wiki/Speed
[modules]: https://zimfw.sh/docs/modules/
[themes]: https://zimfw.sh/docs/themes/
[speed]: https://github.com/zimfw/zimfw/wiki/Speed
[@zimfw]: https://github.com/zimfw
[completion]: https://github.com/zimfw/completion
[zsh-users/zsh-completions]: https://github.com/zsh-users/zsh-completions