# see - See a cute cat.

> cat you see!? It's a fancy cat! :cat:

<img width="1363" alt="image" src="https://github.com/user-attachments/assets/bd253204-deca-4756-bbba-60272e0a367c">

Markdown it's special 🐈

<img width="1363" alt="image" src="https://github.com/user-attachments/assets/b4c3c3ef-8ba5-4ab5-8a3d-55556ca02536">


Images 🖼️ 📷 and more..

https://github.com/user-attachments/assets/8ee492e9-950c-4dcd-a96f-62756b97fe25


> [!WARNING]  
> This project is currently in alpha stage. It may contain bugs, incomplete features, or undergo significant changes. Use with caution and please report any issues you encounter.\*\*

see is a powerful file visualization tool for the terminal, offering advanced code viewing capabilities, Markdown rendering, and more. It provides syntax highlighting, emoji support, and image rendering capabilities, offering a visually appealing way to view various file types directly in your console.

## Features

- State-of-the-art code viewing capabilities with superior syntax highlighting for a wide range of programming languages, powered by tree-sitter
- More accurate, context-aware syntax highlighting
- Minimalistic rich Markdown rendering in the terminal
- Emoji support :smile:
- Image rendering (when possible)
- Clickable links (in supported terminals)
- Table formatting
- Blockquote styling
- And more coming soon!

# Motivation and Context

The primary goal of **see** _(smd before v0.4.0)_ was to create a unified tool for viewing both CLI documentation in Markdown and code files, renderable in both the terminal and web browse

As the project evolved from its initial focus on Markdown, support for viewing code files was added, expanding its utility in diverse development ecosystems. Now, see is your go-to tool for seeing everything that a cat can see!

## Markdown Capabilities

While see has expanded its focus beyond just Markdown, it still offers robust Markdown rendering capabilities:

- Rich text formatting (bold, italic, strikethrough)
- Headers and lists
- Code blocks with syntax highlighting
- Tables
- Blockquotes
- Images (when supported by the terminal)
- Clickable links

## Usage

### 1. Viewing Code Files

see serves as a powerful code viewer for the terminal, providing an efficient way to review code directly in your console with advanced syntax highlighting:

```bash
see path/to/your/code_file.py
see --line-numbers path/to/your/code_file.py  # with line numbers
```

### 2. Rendering Markdown Files

To render a Markdown file, simply pass the path to the file as an argument:

```bash
see path/to/your/markdown_file.md
```

For a live preview in a second tmux pane while you edit:

```bash
see --watch path/to/your/markdown_file.md
```

### 3. Rendering Markdown from Piped Input

see can also read Markdown content from standard input:

```bash
echo "# Hello, *world*" | see
cat README.md | see  # Render a file's content
curl -sL https://raw.githubusercontent.com/guilhermeprokisch/see/master/README.md | see  # Render a remote Markdown file
```

## Installation

There are several ways to install see:

### 1. Install prebuilt binaries via shell script (Recommended)

The easiest and fastest way to install see is by using our shell script:

> [!IMPORTANT]  
> The version number in the URL bellow (v0.9.1) may not be the latest version. Please check the [releases page](https://github.com/guilhermeprokisch/see/releases) for the most recent version and update the URL accordingly before running the command.\*\*

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/guilhermeprokisch/see/releases/download/v0.9.1/see-cat-installer.sh | sh
```

If your shell config is managed by Nix/Home Manager or another setup that makes files like `~/.zshrc` read-only, disable the installer's PATH edits and source Cargo's env file yourself:

```sh
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/guilhermeprokisch/see/releases/download/v0.9.1/see-cat-installer.sh | SEE_CAT_NO_MODIFY_PATH=1 sh
source "$HOME/.cargo/env"
```

If `see` is still shadowed after installation, another `see` earlier in your `PATH` is taking precedence. Running `command -v see` will show which one your shell is using.

### 2. Using prebuilt binaries from GitHub releases

If you prefer to manually download and install the binary:

1. Visit the [see releases page](https://github.com/guilhermeprokisch/see/releases) on GitHub.
2. Find the latest release version.
3. Download the appropriate binary for your operating system and architecture.
4. Extract the downloaded file if necessary.
5. Move the `see` binary to a directory in your system's PATH (e.g., `/usr/local/bin` on Unix-like systems).

### 3. Install prebuilt binaries via Homebrew

If you're using Homebrew, you can install see with:

```sh
brew install guilhermeprokisch/see/see
```

### 4. Using Nix

If you use Nixpkgs directly, package updates may lag behind GitHub releases because that package is maintained separately from this repository.

To try the version currently packaged in Nixpkgs:

```sh
nix-shell -p see-cat
```

To build the version from this repository instead, use the local flake:

```sh
nix build .#see
```

### 5. Using Cargo

You can install see directly from crates.io using Cargo:

```bash
cargo install see-cat
```

This will download, compile, and install the latest version of see. Make sure your Rust installation is up to date.

### 6. Building from Source

If you prefer to build from source or want to contribute to the project:

1. Ensure you have Rust and Cargo installed. If not, get them from [https://rustup.rs/](https://rustup.rs/).

2. Clone the repository:

   ```bash
   git clone https://github.com/guilhermeprokisch/see.git
   cd see
   ```

3. Build and install the project using Cargo:

   ```bash
   cargo install --path .
   ```

This will compile the project and install the `see` binary in your Cargo bin directory, which should be in your PATH.

### 6. Using Nix

This repository now includes a `flake.nix` for development and builds.

```bash
nix develop
```

This opens a shell with the Rust toolchain and common development tools such as `rust-analyzer`, `clippy`, and `rustfmt`.

To build the project with Nix:

```bash
nix build
```

The resulting binary will be available under `./result/bin/see`.

#### Integration with CLI Tools

see can be easily integrated with CLI tools to replace traditional man pages with rich Markdown documentation. Here's an example of how you can use see with a custom CLI tool's --help flag:

```bash
#!/bin/bash

# Name: mycli
# Description: Example CLI tool using see for documentation

if [[ "$1" == "--help" ]]; then
    # Use see to render the Markdown help file
    see ~/.mycli/help.md
else
    # Regular CLI functionality
    echo "Running mycli with arguments: $@"
fi
```

In this example, create a Markdown file at `~/.mycli/help.md` with your CLI documentation. When users run `mycli --help`, they'll see a beautifully rendered version of your Markdown documentation instead of a plain text man page.

<img width="1482" alt="image" src="https://github.com/user-attachments/assets/9b97388e-64d6-4d48-b1a8-614a209f32ee">

This approach allows you to maintain a single source of documentation that's readable in raw form, rendered nicely in the terminal, and viewable in web browsers.

## Library Usage

`see-cat` can now also be used as a library for HTML rendering from a Rust host.

```rust
use see_cat::{render_markdown_to_html, HtmlRenderOptions};

fn main() -> std::io::Result<()> {
    let html = render_markdown_to_html("# Hello from see", &HtmlRenderOptions::default())?;
    println!("{}", html);
    Ok(())
}
```

There are also helpers for files and code blocks:

```rust
use see_cat::{render_code_to_html, render_file_to_html, HtmlRenderOptions};
```

#### Viewing see's Own Documentation

see uses itself to display its own documentation. You can view see's documentation directly in your terminal by running:

```bash
see --help
```

This command will render see's main documentation file `/docs`, giving you a practical example of see in action and providing detailed information about its usage and features.

## Configuration

see supports user-defined configuration files. You can customize various aspects of the rendering process by creating a `config.toml` file in the following location:

- On Linux and macOS: `~/.config/see/config.toml`
- On Windows: `C:\Users\<USERNAME>\AppData\Roaming\see\config.toml`

You can generate a default configuration file by running:

```bash
see --generate-config
```

Here's an example of what you can configure:

```toml
max_image_width = 40
max_image_height = 13
page = false
watch = false
watch_interval_ms = 250
render_images = true
render_links = true
render_table_borders = false
show_line_numbers = true
syntax_theme = "github_light"
syntax_extensions = { ino = "cpp", pde = "cpp" }
```

- `max_image_width` and `max_image_height`: Maximum dimensions for rendered images
- `page`: If true, open text output in see's built-in page mode when writing to a terminal
- `watch`: If true, keep a file preview open and reload it after writes
- `watch_interval_ms`: Polling interval used by watch mode
- `render_images`: If false, images will not be rendered
- `render_links`: If false, links will not be clickable
- `render_table_borders`: If true, tables will be rendered with ASCII borders (default: false)
- `show_line_numbers`: If true, line numbers will be shown for code files (can also be set with `--line-numbers` option)
- `syntax_theme`: Lumis theme name used for syntax highlighting, for example `github_light`, `tokyonight`, `dracula`, or `catppuccin_mocha`
- `syntax_extensions`: Map file extensions to Lumis language names, for example `ino = "cpp"` or `tpl = "html"`

In page mode, long lines are soft-wrapped to the viewport width. Use `r` to force a reload and `q` to quit. With `--watch`, see automatically refreshes when the file changes and follows the bottom by default until you scroll away.

For dark terminals, a good starting point is:

```toml
syntax_theme = "tokyonight"
```

Other themes worth trying are `dracula`, `catppuccin_mocha`, `kanagawa`, and `onedark`.

Note: see uses [tree-sitter](https://github.com/tree-sitter/tree-sitter) via [lumis](https://github.com/leandrocp/lumis) for syntax highlighting. If `syntax_theme` is invalid, see falls back to Lumis' built-in `github_light` theme.

Note: `see` uses Lumis with broad built-in language support. That improves out-of-the-box highlighting coverage, but it also increases binary size.

If you want to force syntax highlighting for custom file types, add them to `syntax_extensions`:

```toml
syntax_extensions = { ino = "cpp", h = "c", templ = "html" }
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. As this project is in alpha, your input and contributions can significantly shape its development.

## Known Issues

As this is an alpha version, you may encounter bugs or incomplete features.

## Tradeoff

`see` currently ships with broad built-in syntax highlighting support by bundling a large Tree-sitter language set in the application. This keeps setup simple and makes highlighting work out of the box for many languages, but it also makes the binary larger than it would be with a smaller curated language set or an extension system.

This is an intentional tradeoff: `see` currently prefers simplicity and broad built-in support over a smaller binary and a more complex install/runtime language management model.

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

3. Theming and Customization: Develop user-customizable color schemes and rendering options