1
0
mirror of https://github.com/Llewellynvdm/starship.git synced 2024-12-25 03:16:01 +00:00

docs: Add vuepress with initial docs (#99)

Co-authored-by: Tiffany Le-Nguyen <tlenguyen@expedia.com>
Co-authored-by: Matan Kushner <hello@matchai.me>
This commit is contained in:
Tiffany Le-Nguyen 2019-07-19 16:18:52 -04:00 committed by Matan Kushner
parent 025c0e5e85
commit 08cf33522a
29 changed files with 10472 additions and 32 deletions

4
.gitignore vendored
View File

@ -13,3 +13,7 @@ Cargo.lock
# Intellij IDE configuration
.idea/
# Compiled files for documentation
docs/node_modules
docs/.vuepress/dist/

28
docs/.vuepress/config.js Normal file
View File

@ -0,0 +1,28 @@
module.exports = {
title: 'Starship',
description: 'The cross-shell prompt for astronauts ☄🌌️',
head: [
['link', { rel: 'icon', href: '/icon.png' }]
],
themeConfig: {
logo: '/icon.png',
sidebar: [
'/',
['/guide/', 'Guide'],
['/config/', 'Configuration']
],
nav: [
{ text: 'Configuration', link: '/config/' },
],
// the GitHub repo path
repo: 'starship/starship',
// the label linking to the repo
repoLabel: 'GitHub',
// if your docs are not at the root of the repo:
docsDir: 'docs',
// defaults to false, set to true to enable
editLinks: true,
// custom text for edit link. Defaults to "Edit this page"
editLinkText: 'Edit this page on GitHub'
}
}

View File

@ -0,0 +1 @@
http://starship-rs.netlify.com/* http://starship.rs/:splat 301!

View File

@ -0,0 +1 @@
../../../media/icon.png

View File

@ -0,0 +1 @@
../../../media/logo.png

View File

@ -0,0 +1 @@
../../../media/logo.svg

View File

@ -0,0 +1,15 @@
$accentColor = #DD0B78
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
.home .hero img
max-width: 500px
min-width: 300px
width: 100%
#main-title
display: none
.hero
margin: 150px 25px

52
docs/README.md Normal file
View File

@ -0,0 +1,52 @@
---
home: true
heroImage: /logo.svg
actionText: Get Started →
actionLink: /guide/
footer: ISC Licensed | Copyright © 2019-present Matan Kushner
---
<div class="features">
<div class="feature">
<h2>Compatibility First</h2>
<p>Works on the most common shells on the most common operating systems. Use it everywhere!</p>
</div>
<div class="feature">
<h2>Rust-Powered</h2>
<p>Brings the best-in-class speed and safety of Rust, to make your prompt as quick and reliable as possible.</p>
</div>
<div class="feature">
<h2>Customizable</h2>
<p>Every little detail is customizable to your liking, to make this prompt as minimal or feature-rich as you'd like it to be.</p>
</div>
</div>
### Quick Install
1. Install the **starship** binary:
```bash
cargo install starship
```
1. Add the init script to your shell's config file:
#### Bash / Zsh
Add the following to the end of `~/.bashrc` or `~/.zshrc`:
```bash
# ~/.bashrc or ~/.zshrc
eval "$(starship init $0)"
```
#### Fish
Add the following to the end of `~/.config/fish/config.fish`:
```sh
# ~/.config/fish/config.fish
eval (starship init fish)
```

336
docs/config/README.md Normal file
View File

@ -0,0 +1,336 @@
# Configuration
::: tip
🔥 Configuration is currently being worked on.
Many new configuration options will be available in coming releases.
:::
To get started configuring starship, create the following file: `~/.config/starship.toml`.
```shell
$ touch ~/.config/starship.toml
```
All configuration for starship is done in this [TOML](https://github.com/toml-lang/toml) file:
```toml
# Replace the "➜" symbol in the prompt with ""
[character] # The name of the module we are confguring is "character"
symbol = "" # The "symbol" segment is being set to ""
# Disable the package module, hiding it from the prompt completely
[package]
disabled = true
```
### Terminology
**Module**: A component in the prompt giving information based on contextual information from your OS. For example, the "nodejs" module shows the version of NodeJS that is currently installed on your computer, if your current directory is a NodeJS project.
**Segment**: Smaller sub-components that compose a module. For example, the "symbol" segment in the "nodejs" module contains the character that is shown before the version number (⬢ by default).
Here is the representation of the node module. In the following example, "symbol" and "version"
are segments within it. Every module also has a prefix and suffix that are the default terminal color.
```
[prefix] [symbol] [version] [suffix]
"via " "⬢" "v10.4.1" ""
```
## Battery
The `battery` module shows how charged the device's battery is and its current charging status.
The module is only visible when the device's battery is below 10%.
### Options
| Variable | Default | Description |
| -------------------- | ------- | ------------------------------------------------- |
| `full_symbol` | `"•"` | The symbol shown when the battery is full. |
| `charging_symbol` | `"⇡"` | The symbol shown when the battery is charging. |
| `discharging_symbol` | `"⇣"` | The symbol shown when the battery is discharging. |
| `disabled` | `false` | Disables the `battery` module. |
### Example
```toml
# ~/.config/starship.toml
[battery]
full_symbol = "🔋"
charging_symbol = "⚡️"
discharging_symbol = "💀"
```
## Character
The `character` module shows a character (usually an arrow) beside where the text
is entered in your terminal.
The character will be green if the status of your
last command had a successful status code (zero), and will be red if the last
command had an unsuccessful status code (non-zero).
### Options
| Variable | Default | Description |
| ---------- | ------- | ---------------------------------------------------- |
| `symbol` | `"➜"` | The symbol used before the text input in the prompt. |
| `disabled` | `false` | Disables the `character` module. |
### Example
```toml
# ~/.config/starship.toml
[character]
symbol = ""
```
## Directory
The `directory` module shows the path to your current directory, truncated to
three parent folders. Your directory will also be truncated to the root of the
git repo that you're currently in.
### Options
| Variable | Default | Description |
| ---------- | ------- | -------------------------------- |
| `disabled` | `false` | Disables the `directory` module. |
## Git Branch
The `git_branch` module shows the active branch of the repo in your current directory.
### Options
| Variable | Default | Description |
| ---------- | ------- | ----------------------------------------------------------------------------- |
| `symbol` | `" "` | The symbol used before the branch name of the repo in your current directory. |
| `disabled` | `false` | Disables the `git_branch` module. |
### Example
```toml
# ~/.config/starship.toml
[git_branch]
symbol = "🌱 "
```
## Git Status
The `git_status` module shows symbols representing the state of the repo in your
current directory.
### Options
| Variable | Default | Description |
| ------------ | ------- | ------------------------------------------------------- |
| `conflicted` | `"="` | This branch has merge conflicts. |
| `ahead` | `"⇡"` | This branch is ahead of the branch being tracked. |
| `behind` | `"⇣"` | This branch is behind of the branch being tracked. |
| `diverged` | `"⇕"` | This branch has diverged from the branch being tracked. |
| `untracked` | `"?"` | There are untracked files in the working directory. |
| `stashed` | `"$"` | A stash exists for the local repository. |
| `modified` | `"!"` | There are file modifications in the working directory. |
| `added` | `"+"` | A new file has been added to the staging area. |
| `renamed` | `"»"` | A renamed file has been added to the staging area. |
| `deleted` | `"✘"` | A file's deletion has been added to the staging area. |
| `disabled` | `false` | Disables the `git_status` module. |
### Example
```toml
# ~/.config/starship.toml
[git_status]
conflicted = "🏳"
ahead = "🏎💨"
behind = "😰"
diverged = "😵"
untracked = "🤷‍"
stashed = "📦"
modified = "📝"
added = ""
renamed = "👅"
deleted = "🗑"
```
## Golang
The `golang` module shows the currently installed version of Golang.
The module will be shown if any of the following conditions are met:
- The current directory contains a `go.mod` file
- The current directory contains a `go.sum` file
- The current directory contains a `glide.yaml` file
- The current directory contains a `Gopkg.yml` file
- The current directory contains a `Gopkg.lock` file
- The current directory contains a `Godeps` directory
- The current directory contains a file with the `.go` extension
### Options
| Variable | Default | Description |
| ---------- | ------- | -------------------------------------------------------- |
| `symbol` | `"🐹 "` | The symbol used before displaying the version of Golang. |
| `disabled` | `false` | Disables the `golang` module. |
### Example
```toml
# ~/.config/starship.toml
[golang]
symbol = "🏎💨 "
```
## Line Break
The `line_break` module separates the prompt into two lines.
### Options
| Variable | Default | Description |
| ---------- | ------- | ------------------------------------------------------------------ |
| `disabled` | `false` | Disables the `line_break` module, making the prompt a single line. |
### Example
```toml
# ~/.config/starship.toml
[line_break]
disabled = true
```
## NodeJS
The `nodejs` module shows the currently installed version of NodeJS.
The module will be shown if any of the following conditions are met:
- The current directory contains a `package.json` file
- The current directory contains a `node_modules` directory
- The current directory contains a file with the `.js` extension
### Options
| Variable | Default | Description |
| ---------- | ------- | -------------------------------------------------------- |
| `symbol` | `"⬢ "` | The symbol used before displaying the version of NodeJS. |
| `disabled` | `false` | Disables the `nodejs` module. |
### Example
```toml
# ~/.config/starship.toml
[nodejs]
symbol = "🤖 "
```
## Package Version
The `package` module is shown when the current directory is the repository for a
package, and shows its current version. The module currently supports `npm` and
`cargo` packages.
- **npm** The `npm` package version is extracted from the `package.json` present
in the current directory
- **cargo** The `cargo` package version is extracted from the `Cargo.toml` present
in the current directory
> ⚠️ The version being shown is that of the package whose source code is in your
> current directory, not your package manager.
### Options
| Variable | Default | Description |
| ---------- | ------- | ---------------------------------------------------------- |
| `symbol` | `"📦 "` | The symbol used before displaying the version the package. |
| `disabled` | `false` | Disables the `package` module. |
### Example
```toml
# ~/.config/starship.toml
[package]
symbol = "🎁 "
```
## Python
The `python` module shows the currently installed version of Python.
The module will be shown if any of the following conditions are met:
- The current directory contains a `.python-version` file
- The current directory contains a `requirements.txt` file
- The current directory contains a `pyproject.toml` file
- The current directory contains a file with the `.py` extension
### Options
| Variable | Default | Description |
| ---------- | ------- | -------------------------------------------------------- |
| `symbol` | `"🐍 "` | The symbol used before displaying the version of Python. |
| `disabled` | `false` | Disables the `python` module. |
### Example
```toml
# ~/.config/starship.toml
[python]
symbol = "👾 "
```
## Rust
The `rust` module shows the currently installed version of Rust.
The module will be shown if any of the following conditions are met:
- The current directory contains a `Cargo.toml` file
- The current directory contains a file with the `.rs` extension
### Options
| Variable | Default | Description |
| ---------- | ------- | -------------------------------------------------------- |
| `symbol` | `"🦀 "` | The symbol used before displaying the version of Python. |
| `disabled` | `false` | Disables the `rust` module. |
### Example
```toml
# ~/.config/starship.toml
[rust]
symbol = "⚙️ "
```
## Username
The `username` module shows active user's username.
The module will be shown if any of the following conditions are met:
- The current user is root
- The current user isn't the same as the one that is logged in
- The user is currently connected as an SSH session
### Options
| Variable | Default | Description |
| ---------- | ------- | ------------------------------- |
| `disabled` | `false` | Disables the `username` module. |
### Example
```toml
# ~/.config/starship.toml
[username]
disabled = true
```

1
docs/guide/README.md Symbolic link
View File

@ -0,0 +1 @@
../../README.md

9986
docs/package-lock.json generated Normal file

File diff suppressed because it is too large Load Diff

9
docs/package.json Normal file
View File

@ -0,0 +1,9 @@
{
"scripts": {
"dev": "vuepress dev",
"build": "vuepress build"
},
"devDependencies": {
"vuepress": "^1.0.2"
}
}

BIN
media/icon.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 126 KiB

1
media/icon.svg Normal file
View File

@ -0,0 +1 @@
<svg fill="none" height="2854" viewBox="0 0 2854 2854" width="2854" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><linearGradient id="a" gradientUnits="userSpaceOnUse" x1="112.463" x2="2365.33" y1="3485.86" y2="-827.778"><stop offset="0" stop-color="#ed0a62"/><stop offset="1" stop-color="#890cea"/></linearGradient><mask id="b" height="2854" maskUnits="userSpaceOnUse" width="2854" x="0" y="0"><circle cx="1427" cy="1427" fill="#c4c4c4" r="1427"/></mask><g mask="url(#b)"><path d="m3351-313h-3849v3480.04h3849z" fill="url(#a)"/><g fill="#fff"><path clip-rule="evenodd" d="m543 785.6c138.837 26.901 217.616 109.138 241.537 241.6-2.462-137.201 79.15-217.068 241.533-241.6-146.358-15.472-224.161-98.824-241.533-241.6-16.814 137.851-91.598 223.666-241.537 241.6z" fill-rule="evenodd"/><path clip-rule="evenodd" d="m1770.54 1814.15-52.67 140.51-432.48-126.28 43.73-150.69-330.462-131.2c105.352-128.74 210.702-191.97 374.182-272.23-14.58-252.74 189.46-433.817 432.47-612.26 193.15 237.105 278.66 447.51 146.61 742.75 109.39 118.55 156.28 308.94 154.52 486.86zm75.18-670.18c0 69.45-56.29 125.76-125.73 125.76-69.43 0-125.72-56.31-125.72-125.76s56.29-125.75 125.72-125.75c69.44 0 125.73 56.3 125.73 125.75z" fill-rule="evenodd"/><path d="m1606.37 2246.91s-97.37 583.09-511.37 731.09l-650-414c572.5 0 777.71-442.31 777.71-442.31z"/></g></g></svg>

After

Width:  |  Height:  |  Size: 1.3 KiB

View File

@ -2,7 +2,7 @@ use ansi_term::Color;
use super::{Context, Module};
/// Creates a segment for the battery percentage and charging state
/// Creates a module for the battery percentage and charging state
pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
const BATTERY_FULL: &str = "";
const BATTERY_CHARGING: &str = "";
@ -28,13 +28,13 @@ pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
match state {
battery::State::Full => {
module.new_segment("full", BATTERY_FULL);
module.new_segment("full_symbol", BATTERY_FULL);
}
battery::State::Charging => {
module.new_segment("charging", BATTERY_CHARGING);
module.new_segment("charging_symbol", BATTERY_CHARGING);
}
battery::State::Discharging => {
module.new_segment("discharging", BATTERY_DISCHARGING);
module.new_segment("discharging_symbol", BATTERY_DISCHARGING);
}
_ => return None,
}

View File

@ -1,9 +1,9 @@
use super::{Context, Module};
use ansi_term::Color;
/// Creates a segment for the prompt character
/// Creates a module for the prompt character
///
/// The char segment prints an arrow character in a color dependant on the exit-
/// The character segment prints an arrow character in a color dependant on the exit-
/// code of the last executed command:
/// - If the exit-code was "0", the arrow will be formatted with `COLOR_SUCCESS`
/// (green by default)
@ -14,7 +14,7 @@ pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
let color_success = Color::Green.bold();
let color_failure = Color::Red.bold();
let mut module = context.new_module("char")?;
let mut module = context.new_module("character")?;
module.get_prefix().set_value("");
let symbol = module.new_segment("symbol", PROMPT_CHAR);

View File

@ -3,7 +3,7 @@ use std::path::Path;
use super::{Context, Module};
/// Creates a segment with the current directory
/// Creates a module with the current directory
///
/// Will perform path contraction and truncation.
/// **Contraction**

View File

@ -2,7 +2,7 @@ use ansi_term::Color;
use super::{Context, Module};
/// Creates a segment with the Git branch in the current directory
/// Creates a module with the Git branch in the current directory
///
/// Will display the branch name if the current directory is a git repo
pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
@ -15,8 +15,8 @@ pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
module.set_style(segment_color);
module.get_prefix().set_value("on ");
module.new_segment("branch_char", GIT_BRANCH_CHAR);
module.new_segment("branch_name", branch_name);
module.new_segment("symbol", GIT_BRANCH_CHAR);
module.new_segment("name", branch_name);
Some(module)
}

View File

@ -3,16 +3,16 @@ use git2::{Repository, Status};
use super::{Context, Module};
/// Creates a segment with the Git branch in the current directory
/// Creates a module with the Git branch in the current directory
///
/// Will display the branch name if the current directory is a git repo
/// By default, the following symbols will be used to represent the repo's status:
/// - `=` This branch has merge conflicts
/// - `⇡` This branch is ahead of the branch being tracked
/// - `` This branch is behind of the branch being tracked
/// - `` This branch is behind of the branch being tracked
/// - `⇕` This branch has diverged from the branch being tracked
/// - `?` — There are untracked files in the working directory
/// - `$` — A stash exists for the repository
/// - `$` — A stash exists for the local repository
/// - `!` — There are file modifications in the working directory
/// - `+` — A new file has been added to the staging area
/// - `»` — A renamed file has been added to the staging area

View File

@ -3,7 +3,7 @@ use std::process::Command;
use super::{Context, Module};
/// Creates a segment with the current Go version
/// Creates a module with the current Go version
///
/// Will display the Go version if any of the following criteria are met:
/// - Current directory contains a `go.mod` file
@ -11,8 +11,8 @@ use super::{Context, Module};
/// - Current directory contains a `glide.yaml` file
/// - Current directory contains a `Gopkg.yml` file
/// - Current directory contains a `Gopkg.lock` file
/// - Current directory contains a `.go` file
/// - Current directory contains a `Godeps` directory
/// - Current directory contains a file with the `.go` extension
pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
let is_go_project = context
.new_scan_dir()

View File

@ -1,6 +1,6 @@
use super::{Context, Module};
/// Creates a segment for the line break
/// Creates a module for the line break
pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
const LINE_ENDING: &str = "\n";

View File

@ -3,7 +3,7 @@ mod character;
mod directory;
mod git_branch;
mod git_status;
mod go;
mod golang;
mod line_break;
mod nodejs;
mod package;
@ -21,7 +21,7 @@ pub fn handle<'a>(module: &str, context: &'a Context) -> Option<Module<'a>> {
"node" | "nodejs" => nodejs::module(context),
"rust" | "rustlang" => rust::module(context),
"python" => python::module(context),
"go" | "golang" => go::module(context),
"go" | "golang" => golang::module(context),
"line_break" => line_break::module(context),
"package" => package::module(context),
"git_branch" => git_branch::module(context),

View File

@ -3,7 +3,7 @@ use std::process::Command;
use super::{Context, Module};
/// Creates a segment with the current Node.js version
/// Creates a module with the current Node.js version
///
/// Will display the Node.js version if any of the following criteria are met:
/// - Current directory contains a `.js` file

View File

@ -5,7 +5,7 @@ use ansi_term::Color;
use serde_json as json;
use toml;
/// Creates a segment with the current package version
/// Creates a module with the current package version
///
/// Will display if a version is defined for your Node.js or Rust project (if one exists)
pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {

View File

@ -3,13 +3,13 @@ use std::process::Command;
use super::{Context, Module};
/// Creates a segment with the current Python version
/// Creates a module with the current Python version
///
/// Will display the Python version if any of the following criteria are met:
/// - Current directory contains a `.py` file
/// - Current directory contains a `.python-version` file
/// - Current directory contains a `requirements.txt` file
/// - Current directory contains a `pyproject.toml` file
/// - Current directory contains a file with the `.py` extension
pub fn module<'a>(context: &'a Context) -> Option<Module<'a>> {
let is_py_project = context
.new_scan_dir()

View File

@ -3,7 +3,7 @@ use std::process::Command;
use super::{Context, Module};
/// Creates a segment with the current Rust version
/// Creates a module with the current Rust version
///
/// Will display the Rust version if any of the following criteria are met:
/// - Current directory contains a file with a `.rs` extension

View File

@ -4,7 +4,7 @@ use std::process::Command;
use super::{Context, Module};
/// Creates a segment with the current user's username
/// Creates a module with the current user's username
///
/// Will display the usename if any of the following criteria are met:
/// - The current user isn't the same as the one that is logged in ($LOGNAME != $USER)

View File

@ -8,12 +8,14 @@ fn char_module_success_status() -> io::Result<()> {
let expected = format!("{} ", Color::Green.bold().paint(""));
// Status code 0
let output = common::render_module("char").arg("--status=0").output()?;
let output = common::render_module("character")
.arg("--status=0")
.output()?;
let actual = String::from_utf8(output.stdout).unwrap();
assert_eq!(expected, actual);
// No status code
let output = common::render_module("char").output()?;
let output = common::render_module("character").output()?;
let actual = String::from_utf8(output.stdout).unwrap();
assert_eq!(expected, actual);
@ -25,19 +27,21 @@ fn char_module_failure_status() -> io::Result<()> {
let expected = format!("{} ", Color::Red.bold().paint(""));
// Error status code 1
let output = common::render_module("char").arg("--status=1").output()?;
let output = common::render_module("character")
.arg("--status=1")
.output()?;
let actual = String::from_utf8(output.stdout).unwrap();
assert_eq!(expected, actual);
// Random non-zero status code
let output = common::render_module("char")
let output = common::render_module("character")
.arg("--status=54321")
.output()?;
let actual = String::from_utf8(output.stdout).unwrap();
assert_eq!(expected, actual);
// Negative status code!?
let output = common::render_module("char")
let output = common::render_module("character")
.arg("--status=-5000")
.output()?;
let actual = String::from_utf8(output.stdout).unwrap();

View File

@ -7,9 +7,9 @@ use crate::common::{self, TestCommand};
fn char_symbol_configuration() -> io::Result<()> {
let expected = format!("{} ", Color::Green.bold().paint(""));
let output = common::render_module("char")
let output = common::render_module("character")
.use_config(toml::toml! {
[char]
[character]
symbol = ""
})
.output()?;