DOCSEARCHbyAlgolia
Submit Docs

see

repository·main·Indexed 43 days ago

https://github.com/guilhermeprokisch/see

A terminal-based file visualization tool for rendering Markdown and code files with high-fidelity syntax highlighting powered by tree-sitter. It supports live preview mode via --watch, piped input from stdin, and can be used as a Rust library (see-cat crate) for rendering Markdown or code blocks into HTML strings. Version 0.10.1.

Tokens
8.1K
Snippets
35
Records
42
Agent score
55%

What's inside see

  1. Use page mode for text output

    main

    When --page=true is enabled, see enters a built-in page mode for text output. This mode provides interactive navigation for viewing rendered content.

    Page mode keys:

    • q: quit
    • r: reload
    • j / k: scroll
    • PgUp / PgDn: page
    • g / G: top or bottom
    see --page=true path/to/your/markdown_file.md

  2. Install see via shell script (Recommended)

    main

    The fastest way to install see is using the provided shell script.

    Important: Check the GitHub releases page to ensure you are using the latest version number in the URL.

    If your shell configuration (like ~/.zshrc) is read-only (e.g., managed by Nix/Home Manager), use the SEE_CAT_NO_MODIFY_PATH=1 environment variable to prevent the installer from attempting to edit your PATH, then source your Cargo environment manually.

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

# Installation for read-only shell configs
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"

  3. View code files with syntax highlighting

    main

    Use see to view code files in your terminal with advanced syntax highlighting powered by tree-sitter. You can also enable line numbers.

    see path/to/your/code_file.py
see --line-numbers path/to/your/code_file.py

  4. Install see via Homebrew, Cargo, or Nix

    main

    Depending on your package manager, you can install see using the following commands:

    • Homebrew: brew install guilhermeprokisch/see/see
    • Cargo: cargo install see-cat (requires Rust installation)
    • Nix (Nixpkgs): nix-shell -p see-cat
    • Nix (Local Flake): nix build .#see
    # Homebrew
brew install guilhermeprokisch/see/see

# Cargo
cargo install see-cat

# Nix
nix-shell -p see-cat
nix build .#see

  5. Render Markdown files

    main

    To render a Markdown file in the terminal, pass the file path as an argument. You can also use the --watch flag to enable a live preview mode that reloads the file whenever it is modified (useful in a second tmux pane).

    # Standard rendering
see path/to/your/markdown_file.md

# Live preview mode
see --watch path/to/your/markdown_file.md
    see path/to/your/markdown_file.md
see --watch path/to/your/markdown_file.md

  6. Render Markdown from piped input

    main

    The see command can process Markdown content from standard input (stdin), allowing you to render content from other CLI tools or remote URLs.

    echo "# Hello, *world*" | see
cat README.md | see
curl -sL https://example.com/README.md | see
    echo "# Hello, *world*" | see
cat README.md | see
curl -sL https://raw.githubusercontent.com/guilhermeprokisch/see/master/README.md | see

  7. Use the see CLI to render files or stdin

    main

    The see tool is a simple Markdown and Code renderer. You can use it to render a specific file or pipe content directly into it via standard input.

    Basic Syntax:

    see [OPTIONS] [FILE]

    If no FILE is provided, see reads from standard input.

    see path/to/your/markdown_file.md

echo "# Hello, world" | see

  8. How the `ViewerManager` handles visualization

    main

    The ViewerManager is responsible for orchestrating the rendering process. It maintains a registry of Viewer implementations and can apply multiple viewers to a single piece of content.

    When calling visualize, the manager:

    1. Checks the global configuration (get_config()). If show_filename is enabled and a file_path is provided, it prints a stylized header containing a file icon (via devicons) and the filename.
    2. Iterates through the requested viewer_names.
    3. For each name, it retrieves the corresponding registered Viewer and calls its visualize method.

    If a requested viewer name is not registered, an error is printed to stderr.

    Supported default viewers:

    • markdown
    • code
    • image

  9. How file watching works in pager mode

    main

    If see is configured with watch = true, the pager mode includes an automatic file watching mechanism.

    • Automatic Reloading: The pager periodically checks the file signatures (existence, length, and modification time) of the source files. If a change is detected, the content is re-rendered and updated in the pager.
    • Follow Bottom: When watching files, if you have scrolled to the bottom of the document (using G), the pager will automatically scroll to the new bottom whenever a reload occurs, ensuring you always see the latest content appended to the file.

  10. How `see` determines which viewer to use

    main

    The see tool automatically selects viewers based on the file extension of the provided path. The determine_viewer function maps extensions to specific viewer names:

    • .md files use the markdown viewer.
    • Image extensions (.jpg, .jpeg, .png, .gif, .bmp, .webp) use the image viewer.
    • All other extensions default to the code viewer.

    This mapping ensures that files are rendered with the appropriate visual representation (e.g., rendered Markdown instead of raw text).

    // Mapping logic used by the tool:
// .md -> "markdown"
// .jpg, .jpeg, .png, .gif, .bmp, .webp -> "image"
// others -> "code"

  11. Force color output with SEE_FORCE_COLORS

    main

    By default, see disables color output if it detects that the output is not a terminal (e.g., when piping to another command). To force color output even when not in a terminal, set the SEE_FORCE_COLORS environment variable.

    SEE_FORCE_COLORS=1 see file.md | cat

  12. Configure see via config.toml

    main

    You can customize rendering behavior by creating a config.toml file.

    Locations:

    • Linux/macOS: ~/.config/see/config.toml
    • Windows: C:\Users\<USERNAME>\AppData\Roaming\see\config.toml

    To generate a default configuration file, run:

    see --generate-config

    Common Configuration Keys:

    • max_image_width / max_image_height: Maximum dimensions for rendered images.
    • page: If true, opens output in built-in page mode (use r to reload, q to quit).
    • watch: If true, keeps a file preview open and reloads on changes.
    • watch_interval_ms: Polling interval for watch mode.
    • render_images: Enables/disables image rendering.
    • render_links: Enables/disables clickable links.
    • render_table_borders: If true, uses ASCII borders for tables.
    • show_line_numbers: Enables/disables line numbers for code.
    • syntax_theme: The Lumis theme name (e.g., github_light, tokyonight, dracula, catppuccin_mocha).
    • syntax_extensions: A map to associate file extensions with language names (e.g., { ino = "cpp" }).
    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" }