Glow can render markdown from various sources, making it flexible for different workflows.
Local Files
Render any markdown file by providing its path:
glow /path/to/document.md
glow ~/Documents/notes.md
~ and environment variables.
Directories
When you provide a directory path, Glow searches for README files:
glow .
glow /path/to/project
README Discovery
Glow searches for these filenames in order (main.go:35):
readmeNames = []string{"README.md", "README", "Readme.md", "Readme", "readme.md", "readme"}
st, err := os.Stat(arg)
if err == nil && st.IsDir() {
var src *source
_ = filepath.Walk(arg, func(path string, _ os.FileInfo, err error) error {
if err != nil {
return err
}
for _, v := range readmeNames {
if strings.EqualFold(filepath.Base(path), v) {
r, err := os.Open(path)
if err != nil {
continue
}
u, _ := filepath.Abs(path)
src = &source{r, u}
// abort filepath.Walk
return errors.New("source found")
}
}
return nil
})
- or by piping content:
Explicit stdin with Dash
echo "# Hello World" | glow -
Automatic Pipe Detection
Glow automatically detects piped input:
curl https://example.com/doc.md | glow
func stdinIsPipe() (bool, error) {
stat, err := os.Stdin.Stat()
if err != nil {
return false, fmt.Errorf("unable to open file: %w", err)
}
if stat.Mode()&os.ModeCharDevice == 0 || stat.Size() > 0 {
return true, nil
}
return false, nil
}
HTTP/HTTPS URLs
Fetch and render markdown from any HTTP(S) URL:
glow https://raw.githubusercontent.com/charmbracelet/glow/main/README.md
glow https://example.com/documentation.md
// HTTP(S) URLs:
if u, err := url.ParseRequestURI(arg); err == nil && strings.Contains(arg, "://") {
if u.Scheme != "" {
if u.Scheme != "http" && u.Scheme != "https" {
return nil, fmt.Errorf("%s is not a supported protocol", u.Scheme)
}
resp, err := http.Get(u.String())
if err != nil {
return nil, fmt.Errorf("unable to get url: %w", err)
}
if resp.StatusCode != http.StatusOK {
return nil, fmt.Errorf("HTTP status %d", resp.StatusCode)
}
return &source{resp.Body, u.String()}, nil
}
}
Only http:// and https:// protocols are supported. Other schemes will return an error.
GitHub Repositories
Glow provides convenient shortcuts for GitHub repositories:
GitHub URL Patterns
# Standard GitHub URL
glow https://github.com/charmbracelet/glow
# Without protocol
glow github.com/charmbracelet/glow
# Using github:// protocol
glow github://charmbracelet/glow
GitHub API Integration
Glow uses the GitHub API to find the README (github.go:14-57):
func findGitHubREADME(u *url.URL) (*source, error) {
owner, repo, ok := strings.Cut(strings.TrimPrefix(u.Path, "/"), "/")
if !ok {
return nil, fmt.Errorf("invalid url: %s", u.String())
}
type readme struct {
DownloadURL string `json:"download_url"`
}
apiURL := fmt.Sprintf("https://api.%s/repos/%s/%s/readme", u.Hostname(), owner, repo)
res, err := http.Get(apiURL)
if err != nil {
return nil, fmt.Errorf("unable to get url: %w", err)
}
- Parses owner and repository from the URL
- Calls GitHub’s README API endpoint
- Downloads the README content
- Works regardless of README filename (README.md, readme.md, etc.)
GitLab Repositories
Similar to GitHub, Glow supports GitLab repository shortcuts:
GitLab URL Patterns
# Standard GitLab URL
glow https://gitlab.com/owner/project
# Without protocol
glow gitlab.com/owner/project
# Using gitlab:// protocol
glow gitlab://owner/project
GitLab API Integration
Glow uses the GitLab API v4 (gitlab.go:14-61):
func findGitLabREADME(u *url.URL) (*source, error) {
owner, repo, ok := strings.Cut(strings.TrimPrefix(u.Path, "/"), "/")
if !ok {
return nil, fmt.Errorf("invalid url: %s", u.String())
}
projectPath := url.QueryEscape(owner + "/" + repo)
type readme struct {
ReadmeURL string `json:"readme_url"`
}
apiURL := fmt.Sprintf("https://%s/api/v4/projects/%s", u.Hostname(), projectPath)
- Extracts owner and project name
- URL-encodes the project path
- Calls GitLab’s projects API
- Converts blob URL to raw URL for content
- Downloads the README
Source Resolution Order
Glow resolves sources in this order (main.go:72-148):
Check for stdin (-)
If argument is -, read from standard input
Try GitHub/GitLab URL
Attempt to parse as GitHub or GitLab repository
Try HTTP(S) URL
Parse as regular HTTP/HTTPS URL
Try Directory
Check if path is directory and search for README
Try Local File
Attempt to open as local file
Examples
Local Files and Directories
# Current directory's README
glow
# Specific file
glow CHANGELOG.md
# Directory with README
glow ~/projects/myapp
Remote Sources
# GitHub shortcut
glow github.com/charmbracelet/glow
# GitLab project
glow gitlab.com/gitlab-org/gitlab
# Direct markdown URL
glow https://raw.githubusercontent.com/owner/repo/main/docs/guide.md
# From pipe
cat notes.md | glow
# From heredoc
glow <<EOF
# Quick Note
This is **important**!
EOF
# From curl
curl -s https://example.com/api/docs.md | glow
Combining with Other Flags
# GitHub repo with custom style
glow github.com/charmbracelet/glow --style pink
# URL with pager
glow https://example.com/doc.md --pager
# Stdin with custom width
echo "# Test" | glow --width 60
When working with GitHub or GitLab repositories, using the URL shortcuts is faster than navigating to the raw file URL, as Glow handles README discovery automatically.
