{"id":35226354,"url":"https://github.com/umputun/weblist","last_synced_at":"2026-02-21T02:04:36.392Z","repository":{"id":282818137,"uuid":"949750562","full_name":"umputun/weblist","owner":"umputun","description":"file browser for the web","archived":false,"fork":false,"pushed_at":"2026-02-13T08:57:48.000Z","size":4908,"stargazers_count":29,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-02-13T11:03:37.558Z","etag":null,"topics":["files","index","listing","web"],"latest_commit_sha":null,"homepage":"https://weblist.umputun.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umputun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["umputun"]}},"created_at":"2025-03-17T04:37:32.000Z","updated_at":"2026-02-13T10:09:58.000Z","dependencies_parsed_at":"2025-03-31T19:24:58.231Z","dependency_job_id":"8ecdfd3c-37a1-48cf-9463-59f4347daf2e","html_url":"https://github.com/umputun/weblist","commit_stats":null,"previous_names":["umputun/weblist"],"tags_count":55,"template":false,"template_full_name":null,"purl":"pkg:github/umputun/weblist","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umputun%2Fweblist","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umputun%2Fweblist/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umputun%2Fweblist/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umputun%2Fweblist/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umputun","download_url":"https://codeload.github.com/umputun/weblist/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umputun%2Fweblist/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29671513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T00:11:43.526Z","status":"online","status_checked_at":"2026-02-21T02:00:07.432Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["files","index","listing","web"],"created_at":"2025-12-30T01:13:23.204Z","updated_at":"2026-02-21T02:04:36.384Z","avatar_url":"https://github.com/umputun.png","language":"Go","readme":"# weblist [![build](https://github.com/umputun/weblist/actions/workflows/ci.yml/badge.svg)](https://github.com/umputun/weblist/actions/workflows/ci.yml) \u0026nbsp;[![Coverage Status](https://coveralls.io/repos/github/umputun/weblist/badge.svg?branch=master)](https://coveralls.io/github/umputun/weblist?branch=master)\n\nA modern, elegant file browser for the web. Weblist provides a clean and intuitive interface for browsing and downloading files from any directory on your server, replacing the ugly default directory listings of Nginx and Apache with a beautiful, functional alternative.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg class=\"logo\" src=\"https://github.com/umputun/weblist/raw/master/site/docs/logo.png\" width=\"400px\" alt=\"Weblist\"/\u003e\n\u003c/div\u003e\n\n## Why weblist?\n\n- **Clean, Modern Interface**: Simple design that improves readability and usability\n- **Security First**: Locked to the root directory - users can't access files outside the specified folder\n- **Intuitive Navigation**: Simple breadcrumb navigation makes it easy to move between directories\n- **Smart Sorting**: Sort files by name, size, or date with a single click\n- **Mobile Friendly**: Works great on phones and tablets, not just desktops\n- **Fast \u0026 Lightweight**: Loads quickly even on slow connections\n- **No Setup Required**: Single binary that just works - no configuration needed\n- **Dark Mode**: Easy on the eyes with both light and dark themes\n- **Optional Authentication**: Password-protect your file listings when needed\n- **Multi-file Selection**: Select and download multiple files as a ZIP archive (optional)\n- **File Upload**: Upload files via click-to-browse, drag-and-drop, or clipboard paste (optional)\n- **SFTP Support**: Access the same files via SFTP for more advanced operations\n- **Syntax Highlighting**: Beautiful code highlighting for various programming languages (optional)\n- **Markdown Rendering**: Markdown files (.md, .markdown) are rendered as formatted HTML with headings, tables, code blocks, and more\n- **JSON API**: Programmatic access to file listings via a simple JSON API\n\n\u003cdetails markdown\u003e\n  \u003csummary\u003eScreenshots\u003c/summary\u003e\n\n![dark-theme](https://github.com/umputun/weblist/raw/master/site/docs/screen-dark.png)\n\n![dark-theme](https://github.com/umputun/weblist/raw/master/site/docs/screen-light.png)\n\n![dark-theme](https://github.com/umputun/weblist/raw/master/site/docs/screen-preview.png)\n\n![dark-theme](https://github.com/umputun/weblist/raw/master/site/docs/screen-login.png)\n\n\u003c/details\u003e\n\n\n## Quick Start\n\n```bash\n# Serve the current directory\nweblist\n\n# Serve a specific directory\nweblist --root /path/to/files\n\n# Use dark theme\nweblist --theme dark\n\n# Specify a different port\nweblist --listen :9000\n\n# Exclude specific files and directories\nweblist --exclude .git --exclude .env\n\n# Enable password protection\nweblist --auth your_password\n\n# Enable syntax highlighting for code files\nweblist --syntax-highlight\n\n# Enable multi-file selection and download\nweblist --multi\n\n# Enable file upload\nweblist --upload.enabled\n\n# Set a custom title for your file server\nweblist --title \"My Files\"\n```\n\n## Installation\n\n### Download Binary\n\nDownload the latest release from the [releases page](https://github.com/umputun/weblist/releases).\n\n### Using Go\n\n```bash\ngo install github.com/umputun/weblist@latest\n```\n\n**Install from homebrew (macOS)**\n\n```bash\nbrew tap umputun/apps\nbrew install umputun/apps/weblist\n```\n\n## Usage\n\n```\nweblist [options]\n```\n\n### Options\n\n- `-l, --listen`: Address to listen on (default: `:8080`) - env: `LISTEN`\n- `-t, --theme`: Theme to use, \"light\" or \"dark\" (default: `light`) - env: `THEME`\n- `-r, --root`: Root directory to serve (default: current directory) - env: `ROOT_DIR`\n- `-e, --exclude`: Files and directories to exclude (can be repeated) - env: `EXCLUDE`\n- `-f, --hide-footer`: Hide footer - env: `HIDE_FOOTER`\n- `-a, --auth`: Enable authentication with the specified password - env: `AUTH`\n- `--auth-user`: Username for authentication (default: `weblist`) - env: `AUTH_USER`\n- `--session-secret`: Secret key for session tokens (auto-generated if not set) - env: `SESSION_SECRET`\n- `--session-ttl`: Session timeout duration (default: `24h`) - env: `SESSION_TTL`\n- `--insecure-cookies`: Allow cookies without secure flag - env: `INSECURE_COOKIES`\n- `-v, --version`: Show version and exit - env: `VERSION`\n- `--dbg`: Debug mode - env: `DEBUG`\n- `--syntax-highlight`: Enable syntax highlighting for code files - env: `SYNTAX_HIGHLIGHT`\n- `--custom-footer`: Custom footer text (can contain HTML) - env: `CUSTOM_FOOTER`\n- `--multi`: Enable multi-file selection and download - env: `MULTI_SELECT`\n- `--recursive-mtime`: Calculate directory mtime from newest nested file - env: `RECURSIVE_MTIME`\n- `--title`: Custom title for the site (used in browser title and home) - env: `TITLE`\n\nUpload Options (with `--upload` prefix):\n- `--upload.enabled`: Enable file upload - env: `UPLOAD_ENABLED`\n- `--upload.max-size`: Max upload size in MB (default: `64`) - env: `UPLOAD_MAX_SIZE`\n- `--upload.overwrite`: Allow overwriting existing files - env: `UPLOAD_OVERWRITE`\n\nSFTP Options (with `--sftp` prefix):\n- `--sftp.enabled`: Enable SFTP server - env: `SFTP_ENABLED`\n- `--sftp.user`: Username for SFTP access - env: `SFTP_USER`\n- `--sftp.address`: Address for SFTP server (default: `:2022`) - env: `SFTP_ADDRESS`\n- `--sftp.key`: SSH private key file (default: `weblist_rsa`) - env: `SFTP_KEY`\n- `--sftp.authorized`: Path to OpenSSH authorized_keys file for public key authentication - env: `SFTP_AUTHORIZED`\n\nBranding Options (with `--brand` prefix):\n- `--brand.name`: Company or organization name to display in navbar - env: `BRAND_NAME`\n- `--brand.color`: Color for navbar (e.g. `3498db` or `#3498db`) - env: `BRAND_COLOR`\n\n## Authentication\n\nWeblist provides optional password protection for your file listings:\n\n```bash\n# Enable authentication with a password\nweblist --auth your_password\n\n# Customize the username (default is \"weblist\")\nweblist --auth your_password --auth-user admin\n\n# Set a specific session secret key\nweblist --auth your_password --session-secret \"your-secret-key\"\n\n# Change session timeout (default is 24 hours)\nweblist --auth your_password --session-ttl 12h\n\n# Enable on non-HTTPS servers or development (not recommended for production)\nweblist --auth your_password --insecure-cookies\n```\n\nWhen authentication is enabled:\n- Users will be prompted with a login screen\n- The username is customizable via the `--auth-user` parameter (defaults to \"weblist\")\n- The password is whatever you specify with the `--auth` parameter\n- Sessions are secured with HMAC-SHA256 signed tokens\n- Session secrets are automatically generated if not explicitly provided\n- Sessions expire after the specified timeout (default: 24 hours)\n- A logout button appears in the top right corner when logged in\n\nAuthentication is completely optional and only activated when the `--auth` parameter is provided.\n\n## SFTP Access\n\nWeblist can also provide SFTP access to the same files:\n\n```bash\n# Enable SFTP with password authentication\nweblist --auth your_password --sftp.enabled --sftp.user sftp_user\n\n# Use a custom SFTP port\nweblist --auth your_password --sftp.enabled --sftp.user sftp_user --sftp.address :2222\n\n# Specify a custom SSH host key file\nweblist --auth your_password --sftp.enabled --sftp.user sftp_user --sftp.key /path/to/ssh_key\n\n# Enable SFTP with public key authentication (no password needed)\nweblist --sftp.enabled --sftp.user sftp_user --sftp.authorized /path/to/authorized_keys\n```\n\nWhen SFTP is enabled:\n- The same directory is served via SFTP and HTTP\n- File exclusions apply to both HTTP and SFTP\n- Authentication can use either:\n  - Password authentication: Uses the same password as HTTP authentication (requires `--auth` parameter)\n  - Public key authentication: Uses OpenSSH-format authorized_keys file (requires `--sftp.authorized` parameter)\n- The username for SFTP is specified with the `--sftp.user` parameter\n- SFTP access is read-only for security reasons\n- SSH host keys are stored to prevent client warnings about changing keys\n  - By default, the key is stored as `weblist_rsa` in the current directory\n  - You can specify a custom key file with `--sftp.key`\n\nSFTP support is optional and only enabled when both `--sftp.enabled` and `--sftp.user` parameters are provided. Either the `--auth` or `--sftp.authorized` parameter is required when enabling SFTP.\n\n## Multi-file Selection\n\nWeblist can optionally allow users to select and download multiple files at once:\n\n```bash\n# Enable multi-file selection and download\nweblist --multi\n```\n\nWhen multi-file selection is enabled:\n\n- Checkboxes appear next to each file and directory in the listing\n- A \"Select All\" checkbox appears in the header for batch selection\n- Selected files and directories are counted and displayed in the header\n- A \"Download Selected\" button appears when at least one item is selected\n- Clicking the button downloads all selected items as a single ZIP archive\n- Entire directories with their contents can be selected and downloaded\n- The feature works seamlessly in both light and dark themes\n\nMulti-file selection is disabled by default for a cleaner interface and can be enabled with the `--multi` flag.\n\n## File Upload\n\nWeblist can optionally allow users to upload files to the currently viewed directory:\n\n```bash\n# Enable file upload\nweblist --upload.enabled\n\n# Set max upload size (default: 64MB)\nweblist --upload.enabled --upload.max-size 128\n\n# Allow overwriting existing files (default: reject duplicates)\nweblist --upload.enabled --upload.overwrite\n```\n\nWhen file upload is enabled:\n- An upload button appears in the toolbar for uploading files via file picker\n- Files can be dragged and dropped onto the file listing area\n- Files can be pasted from the clipboard (e.g., screenshots)\n- Multiple files can be uploaded at once\n- File size is validated both client-side and server-side\n- Duplicate filenames are rejected by default (configurable with `--upload.overwrite`)\n- Path traversal attacks are blocked — files can only be uploaded to valid directories within the root\n- Upload is protected by authentication when auth is enabled\n\nThe upload endpoint accepts `POST /upload` with `multipart/form-data` containing a `path` field (target directory) and one or more `file` fields.\n\nFile upload is disabled by default and can be enabled with the `--upload.enabled` flag.\n\n## Recursive Directory Modification Time\n\nBy default, when sorting by date, directories show their own modification time - which only updates when files are added, removed, or renamed directly within that directory. Modifying a file inside a subdirectory does not change the parent directory's timestamp.\n\nWith `--recursive-mtime` enabled, weblist calculates directory modification time by scanning all nested files and using the newest file's timestamp. This is useful when you want directories sorted by when their content was last updated, regardless of nesting depth.\n\n```bash\n# Enable recursive modification time calculation\nweblist --recursive-mtime\n```\n\n**Tradeoff:** This feature walks the entire directory tree to find the newest file, which can be slow on large directory structures with many nested files. Use with caution on directories containing thousands of files.\n\n## Custom Branding\n\nWeblist allows you to customize the appearance with your organization's branding:\n\n```bash\n# Set a custom organization name in the navigation bar\nweblist --brand.name \"My Company\"\n\n# Set a custom color for the navigation bar (with or without # prefix)\nweblist --brand.color \"#3498db\"\n# or\nweblist --brand.color \"3498db\"\n\n# Use a custom footer text (can contain HTML)\nweblist --custom-footer \"Powered by \u003ca href='https://example.com'\u003eExample\u003c/a\u003e | © 2025\"\n\n# Combine branding options\nweblist --brand.name \"My Company\" --brand.color \"#3498db\" --custom-footer \"© 2025 My Company\"\n```\n\nWhen branding is enabled:\n- Your organization name appears in the navigation bar\n- The specified color is applied to the navigation bar\n- Custom footer text replaces the default footer links (allows HTML links)\n- The branding is consistently displayed across all pages\n- These settings can be combined with all other Weblist options\n\nCustom branding is optional and only activated when the related parameters are provided.\n\n## JSON API\n\nWeblist provides a JSON API for programmatic access to file listings:\n\n```\nGET /api/list?path=path/to/directory\u0026sort=+name\n```\n\n### API Parameters\n\n- `path`: The directory path to list (default: root directory)\n- `sort`: The sort criteria with direction prefix (optional, default: `+name`):\n  - `+name` or `-name`: Sort by name (ascending or descending)\n  - `+size` or `-size`: Sort by file size (ascending or descending)\n  - `+mtime` or `-mtime`: Sort by modification time (ascending or descending)\n\n### Example Request\n\n```\nGET /api/list?path=docs\u0026sort=-size\n```\n\n### Example Response\n\n```json\n{\n  \"path\": \"docs\",\n  \"files\": [\n    {\n      \"name\": \"..\",\n      \"path\": \".\",\n      \"is_dir\": true,\n      \"size\": 0,\n      \"size_human\": \"-\",\n      \"last_modified\": \"2023-01-01T12:00:00Z\",\n      \"time_str\": \"01-Jan-2023 12:00:00\",\n      \"is_viewable\": false\n    },\n    {\n      \"name\": \"images\",\n      \"path\": \"docs/images\",\n      \"is_dir\": true,\n      \"size\": 0,\n      \"size_human\": \"-\",\n      \"last_modified\": \"2023-01-01T12:00:00Z\",\n      \"time_str\": \"01-Jan-2023 12:00:00\",\n      \"is_viewable\": false\n    },\n    {\n      \"name\": \"document.pdf\",\n      \"path\": \"docs/document.pdf\",\n      \"is_dir\": false,\n      \"size\": 1048576,\n      \"size_human\": \"1.0M\",\n      \"last_modified\": \"2023-01-01T12:00:00Z\",\n      \"time_str\": \"01-Jan-2023 12:00:00\",\n      \"is_viewable\": true\n    }\n  ],\n  \"sort\": \"size\",\n  \"dir\": \"desc\"\n}\n```\n\nThe JSON API provides all the same functionality as the web interface, including respecting exclusion rules, authentications, and sorting preferences.\n\n### Accessing Files\n\nTo download or access individual files, you can use a simple GET request to the file path:\n\n```\nGET /{path/to/file}\n```\n\nFor example:\n```\nGET /docs/document.pdf\n```\n\nThis will:\n- Return the file with the appropriate Content-Type header\n- Set Content-Disposition to \"attachment\" for binary files\n- Allow direct viewing in the browser for compatible file types (text, HTML, images, PDFs)\n\nThe path format matches exactly what's returned in the `path` field of the JSON API response.\n\nFor viewing text files or code in the browser with syntax highlighting (when enabled):\n```\nGET /view/{path/to/file}\n```\n\nMarkdown files (`.md`, `.markdown`) are automatically rendered as formatted HTML with support for GFM (GitHub Flavored Markdown) — headings, tables, task lists, fenced code blocks with syntax highlighting, and more. This happens automatically without any configuration.\n\nAll file access respects the same authentication and exclusion rules as the web interface.\n\n## Docker\n\nPerfect for NAS devices or home servers:\n\n```bash\ndocker run -p 8080:8080 -v /path/to/files:/data umputun/weblist\n```\n\n### Docker Compose\n\n```yaml\nversion: '3'\nservices:\n  weblist:\n    image: ghcr.io/umputun/weblist:latest\n    container_name: weblist\n    restart: always\n    ports:\n      - \"8080:8080\"\n      - \"2022:2022\"  # SFTP port\n    volumes:\n      - /path/to/files:/data:ro  # use /path/to/files:/data (without :ro) if upload is enabled\n    environment:\n      - LISTEN=:8080\n      - THEME=light\n      - ROOT_DIR=/data\n      - EXCLUDE=.git,.env\n      - AUTH=your_password  # Optional: Enable password authentication\n      - AUTH_USER=admin  # Optional: Custom username for authentication (default: weblist)\n      - SESSION_SECRET=your_secure_key  # Optional: Secret for signing session tokens\n      - SESSION_TTL=24h  # Optional: Session timeout duration\n      - BRAND_NAME=My Company  # Optional: Display company name in navbar\n      - BRAND_COLOR=#3498db  # Optional: Custom color for navbar\n      - CUSTOM_FOOTER=\"\u003ca href='https://example.com'\u003eExample\u003c/a\u003e | © 2025\"  # Optional: Custom footer text\n      - SFTP_ENABLED=true   # Optional: Enable SFTP server\n      - SFTP_USER=sftp_user # Optional: Username for SFTP access\n      - SFTP_ADDRESS=:2022  # Optional: SFTP port\n      - SFTP_KEY=/data/ssh_key  # Optional: Path to SSH host key\n      - SFTP_AUTHORIZED=/data/authorized_keys  # Optional: Path to authorized_keys file for public key auth\n      - SYNTAX_HIGHLIGHT=true  # Optional: Enable syntax highlighting for code files\n      - MULTI_SELECT=true  # Optional: Enable multi-file selection and download\n      - UPLOAD_ENABLED=true  # Optional: Enable file upload\n      - UPLOAD_MAX_SIZE=64  # Optional: Max upload size in MB (default: 64)\n      - UPLOAD_OVERWRITE=false  # Optional: Allow overwriting existing files\n      - RECURSIVE_MTIME=true  # Optional: Calculate directory mtime from newest nested file\n      - TITLE=My File Server  # Optional: Custom title for the site\n```\n","funding_links":["https://github.com/sponsors/umputun"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumputun%2Fweblist","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumputun%2Fweblist","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumputun%2Fweblist/lists"}