Glow

Running glow without any arguments launches the Textual User Interface (TUI).

• Browsing: Glow automatically finds local markdown files in the current directory and subdirectories. If you are inside a Git repository, it will search the entire repository.
• Navigation: The TUI uses a high-performance pager. Most keystrokes are identical to less.
• Help: Press ? to list available hotkeys.

To avoid repeating flags, you can create a configuration file. Run glow config to open the default configuration file in your $EDITOR. Alternatively, manually create a glow.yml file in your platform's default config path.

Configuration Keys

style: "light"
mouse: true
pager: true
width: 80
all: false
showLineNumbers: false
preserveNewLines: false

Glow uses a multi-step resolution process to identify the markdown source provided in an argument:

1. Stdin: If the argument is -, it reads from os.Stdin.
2. README URLs: It attempts to resolve the argument as a GitHub or GitLab README URL.
3. HTTP(S) URLs: It parses the argument as a URI. If it uses http or https, it fetches the content via an HTTP GET request.
4. Directories: If the argument is a directory, Glow walks the directory to find the first file matching common README names (e.g., README.md, readme, README).
5. Files: If the argument is a path to a file, it opens that file directly.

Glow is a CLI tool for rendering markdown with high-quality terminal styling. You can provide a file path, a directory, a URL, or pipe content via stdin.

Common Usage Patterns

Render a local file:

glow README.md

Render from stdin:

cat file.md | glow -

Render a directory (TUI mode): If you provide a directory, Glow enters its Terminal User Interface (TUI) mode to browse files.

glow ./docs

Render a URL: Glow supports HTTP/HTTPS URLs and can even handle GitHub/GitLab README links.

glow https://example.com/README.md

glow [SOURCE|DIR]

Glow uses viper to manage configuration. It looks for a glow.yml file in the following locations:

1. Directories specified by XDG_CONFIG_HOME/glow.
2. Directories specified by GLOW_CONFIG_HOME.
3. Default user configuration directories (via go-app-paths).

Environment variables with the prefix GLOW_ can also be used to override settings (e.g., GLOW_STYLE=dark).

Supported Configuration Keys

• style: The Glamour style to use.
• width: Word-wrap width.
• all: Whether to show all files in TUI.
• pager: Whether to use a pager.
• tui: Whether to use the TUI.
• mouse: Enable mouse support in TUI.
• preserveNewLines: Whether to preserve newlines.
• showLineNumbers: Whether to show line numbers in TUI.

Glow uses a YAML configuration file to manage user preferences. The configuration supports the following keys:

Default Configuration Template:

# style name or JSON path (default "auto")
style: "auto"
# mouse support (TUI-mode only)
mouse: false
# use pager to display markdown
pager: false
# word-wrap at width
width: 80
# show all files, including hidden and ignored.
all: false

Use the following flags to customize CLI output:

• -w <width>: Set the maximum width for word wrapping.
• -p: Use a pager to display the output (defaults to less -r if $PAGER is unset).
• -s <style>: Choose a visual style. Options include dark, light, or a path to a custom JSON stylesheet.

Example: glow -w 60 -s dark

Glow provides a CLI for rendering markdown from various sources directly to the terminal.

Common Commands

• Read from a local file: glow <filename>
• Read from stdin: echo "markdown content" | glow -
• Fetch from GitHub/GitLab: glow <repository_url>
• Fetch from HTTP: glow <url>

glow README.md

The findGitLabREADME function attempts to locate and retrieve the raw content of a README file from a GitLab repository using the GitLab API.

It works by:

1. Parsing the owner and repository name from a provided GitLab URL.
2. Querying the GitLab API (/api/v4/projects/{project_path}) to find the readme_url.
3. Converting the blob URL to a raw URL to access the plain text content.
4. Returning a source object containing the raw body and the URL.

Note: This function requires a valid GitLab URL and access to the GitLab API. It returns an error if the URL is invalid, the API request fails, or the README cannot be found.

// Example usage (conceptual based on function signature)
// u must be a *url.URL pointing to a GitLab project
src, err := findGitLabREADME(u)
if err != nil {
    // handle error
}
// src contains the resp.Body and the readmeRawURL

The readmeURL function resolves a path or URL into a *source. It supports several input formats:

• GitHub custom protocol: Uses github:// prefix (e.g., github://owner/repo).
• GitLab custom protocol: Uses gitlab:// prefix (e.g., gitlab://owner/repo).
• HTTPS URLs: Standard web URLs.
• Relative paths: If a path does not have a protocol prefix, https:// is prepended automatically.

If the URL points to GitHub or GitLab, the function will attempt to find the corresponding README file via findGitHubREADME or findGitLabREADME.

// Example usage
source, err := readmeURL("github://charmbracelet/glow")

Use isURL to determine if a given string is a valid URI that contains a scheme (e.g., https://). It returns true if the string can be parsed as a request URI and contains the :// separator.

// Example usage
valid := isURL("https://example.com") // true
invalid := isURL("not-a-url")        // false