startpage

Startpage

A minimal, keyboard-driven browser startpage with bookmark management and customizable themes.

Features

• Keyboard-First Navigation: Navigate and search entirely with your keyboard
• Real-time Bookmark Search: Instantly filter bookmarks by name, URL, or tags
• Command System: Vim-style commands for quick actions
• Customizable Appearance: Configure colors, background images, blur, and mask overlays
• Smart URL Detection: Automatically opens domains or searches the web
• Import/Export: Backup and restore your settings and bookmarks
• localStorage Support: All settings persist locally with JSON fallback

Quick Start

1. Clone this repository bash git clone https://github.com/aaaooai/startpage.git cd startpage
2. Open docs/index.html in your browser
3. Set it as your browser's homepage

Local Development with Docker/Podman

You can run the startpage locally using Docker or Podman:

Using Docker Compose or Podman Compose:

docker compose up -d
# or
podman compose up -d

Using Docker or Podman directly:

# Docker
docker run --rm -it -v ./docs:/usr/share/nginx/html -p 8000:80 nginx:latest

# Podman
podman run --rm -it -v ./docs:/usr/share/nginx/html:Z -p 8000:80 docker.io/nginx:latest

Then access at http://localhost:8000

GitHub Pages Deployment

The startpage is designed to work with GitHub Pages:

1. Push the repository to GitHub
2. Enable GitHub Pages in repository settings
3. Select the docs folder as the source
4. Access at https://<username>.github.io/<repository>/

Usage

Basic Search

• Type to search: Start typing to filter bookmarks in real-time
• Direct URL: Enter a domain (e.g., github.com) to open it directly
• Web search: Enter any text to search with your configured search engine
• Arrow keys: Navigate through results with ↑ and ↓
• Enter: Open selected bookmark or perform search
• Escape: Clear input field

Commands

All commands start with : and support autocomplete:

• :list - Show all bookmarks
• :config - Open settings page
• :bookmark - Edit bookmarks
• :export - Export settings and bookmarks as JSON
• :import - Import settings and bookmarks from JSON
• :help - Show keyboard shortcuts
• :reset - Reset all settings to default (with confirmation)

Managing Bookmarks

Access the bookmark editor with :bookmark or navigate to bookmarks.html.

Adding Bookmarks

• Click any + button between bookmarks to insert at that position
• Fill in the name, URL, and optional tags
• Changes are saved automatically

Editing Bookmarks

• Name: Required field (displays in search results)
• URL: Required field, must be a valid URL format
• Tags: Optional, comma-separated with space after comma (e.g., dev, code, web)
• Invalid fields are highlighted with a red border
• Tags are auto-formatted on blur

Reordering Bookmarks

• Drag bookmarks by the ≡ handle on the right
• A blue line shows where the bookmark will be inserted
• Order is saved automatically

Deleting Bookmarks

• Click the × button in the top-right corner of any bookmark
• Confirmation dialog will appear
• Invalid bookmarks (empty URL) are removed when navigating back to the startpage

Customizing Appearance

Access settings with :config or navigate to config.html.

Basic Colors

• Background Color: Main background color
• Text Color: Primary text color
• Accent Color: Highlight color for selected items and borders

Background Image

• Background Image URL: Local file path or external URL
• Background Blur: 0-20px blur effect (use slider)
• Mask Color: Color overlay on background image
• Mask Opacity: 0-100% opacity for mask (use slider, default: 60%)

Tip: Use blur and mask to improve text readability over background images

Search Engine

Enter your preferred search engine URL with query parameter, e.g.:

• https://www.google.com/search?q=
• https://duckduckgo.com/?q=
• https://www.startpage.com/search?q=

All settings are previewed in real-time and saved automatically.

Sharing Configuration

You can share your configuration and bookmarks across devices using Git:

1. Export your current settings using :export
2. Copy the exported content to docs/data.json
3. Commit and push to Git: bash git add docs/data.json git commit -m "Update shared configuration" git push
4. On other devices, pull the changes and use :reset to clear localStorage, then reload to use the shared configuration

Data Management

Export Settings

1. Use :export command
2. A JSON file will download with timestamp: startpage-export-YYYY-MM-DD.json
3. Contains all settings and bookmarks

Import Settings

1. Use :import command
2. Select a previously exported JSON file
3. Page will reload with imported settings

Reset to Default

1. Use :reset command
2. Confirm the action
3. All localStorage data is cleared and page reloads

File Structure

startpage/
├── docs/
│   ├── index.html          # Main startpage
│   ├── config.html         # Settings page
│   ├── bookmarks.html      # Bookmark editor
│   ├── script.js           # Main application logic
│   ├── style.css           # Shared styles
│   └── data.json           # Default configuration and bookmarks (fallback)
├── compose.yaml            # Docker Compose configuration
└── README.md

Default Data Structure

The data.json file contains both configuration and bookmarks:

{
  "config": {
    "backgroundColor": "#000000",
    "textColor": "#ffffff",
    "accentColor": "#4a9eff",
    "searchEngine": "https://www.startpage.com/search?q=",
    "backgroundImage": "",
    "backgroundBlur": 0,
    "maskColor": "#000000",
    "maskOpacity": 60
  },
  "bookmarks": [
    {
      "name": "GitHub",
      "url": "https://github.com",
      "tags": ["dev", "code"]
    }
  ]
}

This matches the export format, making it easy to share configurations via Git.

Keyboard Shortcuts

Key	Action
Type	Auto-focus search and filter bookmarks
:	Show command suggestions
↓ / ↑	Navigate results
Enter	Open bookmark / Execute command / Search
Esc	Clear input / Close help

Browser Compatibility

• Modern browsers with ES6+ support
• localStorage API required
• Tested on: Chrome, Firefox, Safari, Edge

Privacy

• All data stored locally in browser's localStorage
• No external requests except for user-configured background images
• No analytics or tracking

License

MIT License - Feel free to modify and use as you wish.