Add Mkdocs

2020-11-19 23:49:41 +01:00 · 2020-11-19 23:49:41 +01:00 · 037c47c093
parent 04f75a10a5
commit 037c47c093
13 changed files with 209 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -1 +1,2 @@
 *.zwc
+.env
--- a/docs/features.md
+++ b/docs/features.md
@ -0,0 +1,7 @@
+# Features
+
+* [Configuration wizard](features/wizard.md)
+* [Uncompromising performance](features/uncompromising_performance.md)
+* [Powerlevel10k Compatibility](features/p10k_compatibility.md)
+* [Pure compatibility](features/pure_compatibility.md)
+* [Instant prompt](features/instant_prompt.md)
--- a/docs/features/instant_prompt.md
+++ b/docs/features/instant_prompt.md
@ -0,0 +1,22 @@
+# Instant prompt
+
+If your `~/.zshrc` loads many plugins, or perhaps just a few slow ones
+(for example, [pyenv](https://github.com/pyenv/pyenv) or [nvm](https://github.com/nvm-sh/nvm)), you
+may have noticed that it takes some time for Zsh to start.
+
+![Powerlevel10k No Instant Prompt](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/no-instant-prompt.gif)
+
+Powerlevel10k can remove Zsh startup lag **even if it's not caused by a theme**.
+
+![Powerlevel10k Instant Prompt](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/instant-prompt.gif)
+
+This feature is called *Instant Prompt*. You need to explicitly enable it through `p10k configure`
+or [manually](#how-do-i-enable-instant-prompt). It does what it says on the tin -- prints prompt
+instantly upon Zsh startup allowing you to start typing while plugins are still loading.
+
+Other themes *increase* Zsh startup lag -- some by a lot, others by a just a little. Powerlevel10k
+*removes* it outright.
+
+*FAQ:* [How do I enable instant prompt?](#how-do-i-enable-instant-prompt)
--- a/docs/features/p10k_compatibility.md
+++ b/docs/features/p10k_compatibility.md
@ -0,0 +1,22 @@
+# Powerlevel9k compatibility
+
+Powerlevel10k understands all [Powerlevel9k](https://github.com/Powerlevel9k/powerlevel9k)
+configuration parameters.
+
+![Powerlevel10k Compatibility with 9k](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/9k-compatibility.gif)
+
+[Migration](#installation) from Powerlevel9k to Powerlevel10k is a straightforward process. All
+your `POWERLEVEL9K` configuration parameters will still work. Prompt will look the same as before
+([almost](
+  #does-powerlevel10k-always-render-exactly-the-same-prompt-as-powerlevel9k-given-the-same-config))
+but it will be [much faster](#uncompromising-performance) ([certainly](#is-it-really-fast)).
+
+*FAQ*:
+
+- [I'm using Powerlevel9k with Oh My Zsh. How do I migrate?](
+    #im-using-powerlevel9k-with-oh-my-zsh-how-do-i-migrate)
+- [Does Powerlevel10k always render exactly the same prompt as Powerlevel9k given the same config?](
+    #does-powerlevel10k-always-render-exactly-the-same-prompt-as-powerlevel9k-given-the-same-config)
+- [What is the relationship between Powerlevel9k and Powerlevel10k?](
+    #What-is-the-relationship-between-powerlevel9k-and-powerlevel10k)
--- a/docs/features/pure_compatibility.md
+++ b/docs/features/pure_compatibility.md
@ -0,0 +1,18 @@
+# Pure compatibility
+
+Powerlevel10k can produce the same prompt as [Pure](https://github.com/sindresorhus/pure). Type
+`p10k configure` and select *Pure* style.
+
+![Powerlevel10k Pure Style](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/pure-style.gif)
+
+You can still use Powerlevel10k features such as [transient prompt](#transient-prompt) or
+[instant prompt](#instant-prompt) when sporting Pure style.
+
+To customize prompt, edit `~/.p10k.zsh`. Powerlevel10k doesn't recognize Pure configuration
+parameters, so you'll need to use `POWERLEVEL9K_COMMAND_EXECUTION_TIME_THRESHOLD=3` instead of
+`PURE_CMD_MAX_EXEC_TIME=3`, etc. All relevant parameters are in `~/.p10k.zsh`. This file has
+plenty of comments to help you navigate through it.
+
+*FAQ:* [What is the best prompt style in the configuration wizard?](
+  #what-is-the-best-prompt-style-in-the-configuration-wizard)
--- a/docs/features/show_on_command.md
+++ b/docs/features/show_on_command.md
@ -0,0 +1,25 @@
+# Show on command
+
+The behavior of some commands depends on global environment. For example, `kubectl run ...` runs an
+image on the cluster defined by the current kubernetes context. If you frequently change context
+between "prod" and "testing", you might want to display the current context in Zsh prompt. If you do
+likewise for AWS, Azure and Google Cloud credentials, prompt will get pretty crowded.
+
+Enter *Show On Command*. This feature makes prompt segments appear only when they are relevant to
+the command you are currently typing.
+
+![Powerlevel10k Show On Command](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/show-on-command.gif)
+
+Configs created by `p10k configure` enable show on command for several prompt segments by default.
+Here's the relevant parameter for kubernetes context:
+
+```zsh
+# Show prompt segment "kubecontext" only when the command you are typing
+# invokes kubectl, helm, kubens, kubectx, oc, istioctl, kogito, k9s or helmfile.
+typeset -g POWERLEVEL9K_KUBECONTEXT_SHOW_ON_COMMAND='kubectl|helm|kubens|kubectx|oc|istioctl|kogito|k9s|helmfile'
+```
+
+To customize when different prompt segments are shown, open `~/.p10k.zsh`, search for
+`SHOW_ON_COMMAND` and either remove these parameters to display affected segments unconditionally,
+or change their values.
--- a/docs/features/transient_prompt.md
+++ b/docs/features/transient_prompt.md
@ -0,0 +1,13 @@
+# Transient prompt
+
+When *Transient Prompt* is enabled through `p10k configure`, Powerlevel10k will trim down every
+prompt when accepting a command line.
+
+![Powerlevel10k Transient Prompt](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/transient-prompt.gif)
+
+Transient prompt makes it much easier to copy-paste series of commands from the terminal scrollback.
+
+*Tip*: If you enable transient prompt, take advantage of two-line prompt. You'll get the benefit of
+extra space for typing commands without the usual drawback of reduced scrollback density. Sparse
+prompt (with an empty line before prompt) also works great in combination with transient prompt.
--- a/docs/features/uncompromising_performance.md
+++ b/docs/features/uncompromising_performance.md
@ -0,0 +1,25 @@
+# Uncompromising performance
+
+When you hit *ENTER*, the next prompt appears instantly. With Powerlevel10k there is no prompt lag.
+If you install Cygwin on Raspberry Pi, `cd` into a Linux Git repository and activate enough prompt
+segments to fill four prompt lines on both sides of the screen... wait, that's just crazy and no
+one ever does that. Probably impossible, too. The point is, Powerlevel10k prompt is always fast, no
+matter what you do!
+
+![Powerlevel10k Performance](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/performance.gif)
+
+Note how the effect of every command is instantly reflected by the very next prompt.
+
+| Command                       | Prompt Indicator | Meaning                                                               |
+|-------------------------------|:----------------:|----------------------------------------------------------------------:|
+| `timew start hack linux`      | `🛡️ hack linux`  | time tracking enabled in [timewarrior](https://timewarrior.net/)      |
+| `touch x y`                   | `?2`             | 2 untracked files in the Git repo                                     |
+| `rm COPYING`                  | `!1`             | 1 unstaged change in the Git repo                                     |
+| `echo 3.7.3 >.python-version` | `🐍 3.7.3`       | the current python version in [pyenv](https://github.com/pyenv/pyenv) |
+
+Other Zsh themes capable of displaying the same information either produce prompt lag or print
+prompt that doesn't reflect the current state of the system and then refresh it later. With
+Powerlevel10k you get fast prompt *and* up-to-date information.
+
+*FAQ*: [Is it really fast?](#is-it-really-fast)
--- a/docs/features/wizard.md
+++ b/docs/features/wizard.md
@ -0,0 +1,35 @@
+# Configuration wizard
+
+Type `p10k configure` to access the builtin configuration wizard right from your terminal.
+
+![Powerlevel10k Configuration Wizard](
+  https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/configuration-wizard.gif)
+
+All styles except [Pure](#pure-compatibility) are functionally equivalent. They display the same
+information and differ only in presentation.
+
+Configuration wizard creates `~/.p10k.zsh` based on your preferences. Additional prompt
+customization can be done by editing this file. It has plenty of comments to help you navigate
+through configuration options.
+
+*Tip*: Install [the recommended font](#meslo-nerd-font-patched-for-powerlevel10k) before
+running `p10k configure` to unlock all prompt styles.
+
+*FAQ:*
+
+- [What is the best prompt style in the configuration wizard?](
+    #what-is-the-best-prompt-style-in-the-configuration-wizard)
+- [What do different symbols in Git status mean?](
+    #what-do-different-symbols-in-git-status-mean)
+- [How do I change prompt colors?](#how-do-i-change-prompt-colors)
+
+*Troubleshooting*:
+
+- [Some prompt styles are missing from the configuration wizard](
+    #some-prompt-styles-are-missing-from-the-configuration-wizard).
+- [Question mark in prompt](#question-mark-in-prompt).
+- [Icons, glyphs or powerline symbols don't render](#icons-glyphs-or-powerline-symbols-dont-render).
+- [Sub-pixel imperfections around powerline symbols](
+    #sub-pixel-imperfections-around-powerline-symbols).
+- [Directory is difficult to see in prompt when using Rainbow style](
+    #directory-is-difficult-to-see-in-prompt-when-using-rainbow-style).
--- a/docs/font.md
+++ b/docs/font.md
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@ -0,0 +1,19 @@
+# Get Started
+
+1. Install [the recommended font](font.md). *Optional but highly
+   recommended.*
+2. Install Powerlevel10k for your plugin manager.
+   - [Manual](#manual) 👈 **choose this if confused or uncertain**
+   - [Oh My Zsh](#oh-my-zsh)
+   - [Prezto](#prezto)
+   - [Zim](#zim)
+   - [Antibody](#antibody)
+   - [Antigen](#antigen)
+   - [Zplug](#zplug)
+   - [Zgen](#zgen)
+   - [Zplugin](#zplugin)
+   - [Zinit](#zinit)
+   - [Homebrew](#homebrew)
+   - [Arch Linux](#arch-linux)
+3. Restart Zsh.
+4. Type `p10k configure` if the configuration wizard doesn't start automatically.
--- a/docs/index.md
+++ b/docs/index.md
@ -0,0 +1,8 @@
+# Powerlevel10k Docs
+
+Powerlevel10k is a theme for Zsh. It emphasizes [speed](#uncompromising-performance),
+[flexibility](#extremely-customizable) and [out-of-the-box experience](#configuration-wizard).
+
+![Powerlevel10k](
+https://raw.githubusercontent.com/romkatv/powerlevel10k-media/master/prompt-styles-high-contrast.png)
+
--- a/mkdocs.yml
+++ b/mkdocs.yml
@ -0,0 +1,14 @@
+site_name: Powerlevel10k Documentation
+repo_url: https://github.com/romkatv/powerlevel10k
+edit_uri: null
+nav:
+  - Home: index.md
+  - Get Started: getting_started.md
+  - Features:
+      - 'Configuration wizard': 'features/wizard.md'
+      - 'Uncompromising performance': 'features/uncompromising_performance.md'
+      - 'Powerlevel10k Compatibility': 'features/p10k_compatibility.md'
+      - 'Pure compatibility': 'features/pure_compatibility.md'
+      - 'Instant prompt': 'features/instant_prompt.md'
+      - 'Show on command': 'features/show_on_command.md'
+      - 'Transient prompt': 'features/transient_prompt.md'