Add project website

.github/workflows/website.yml

@@ -0,0 +1,72 @@
+name: Website
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "website/**"
+      - ".github/workflows/website.yml"
+  pull_request:
+    paths:
+      - "website/**"
+      - ".github/workflows/website.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: website-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build website
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 11.13.0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: website/pnpm-lock.yaml
+
+      - name: Install website dependencies
+        working-directory: website
+        run: pnpm install --frozen-lockfile
+
+      - name: Build website
+        working-directory: website
+        run: pnpm docs:build
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: website/.vitepress/dist
+
+  deploy:
+    name: Deploy website
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -3,6 +3,10 @@
 /dist/
 *.out
 
+# Website dependencies and generated site
+/website/node_modules/
+/website/.vitepress/dist/
+
 # Test and coverage outputs
 coverage.txt
 coverage.html

docs/decisions/0003-project-website.md

@@ -0,0 +1,98 @@
+# ADR 0003: Publish the project website with VitePress and GitHub Pages
+
+- Status: proposed
+- Date: 2026-08-03
+
+## Context
+
+Bible CLI needs a public project website that provides a clear first impression
+for prospective users and a durable home for installation, usage, command
+reference, configuration, and release documentation. The site should be simple
+for Go contributors to maintain: documentation changes should be ordinary
+Markdown pull requests reviewed alongside the code they describe.
+
+The project does not need server-side rendering, a database, accounts, or other
+dynamic application infrastructure. Maintaining a separate hosting system or
+deploying generated site files to a branch would add operational work without
+helping users.
+
+## Decision
+
+Use [VitePress](https://vitepress.dev/) to build a static project website from
+Markdown files stored in this repository. The initial site will include:
+
+- a landing page explaining Bible CLI, its offline-first approach, and supported
+  platforms;
+- installation and quick-start guides;
+- guides for reading, searching, configuration, shell completion, and Bible
+  translation attribution; and
+- a command reference generated or maintained from the CLI's documented command
+  surface.
+
+Host the generated site on GitHub Pages. Start at the repository Pages URL
+(`https://vmrocha.github.io/bible-cli/`) and attach a project-owned custom
+domain later, when one is available. Require HTTPS for the custom domain.
+
+Keep VitePress source and configuration under `website/`. Configure its public
+base path as `/bible-cli/` while using the GitHub Pages project URL; change it
+to `/` when moving to a custom domain.
+
+Deploy with a GitHub Actions workflow that runs on pushes to `main` affecting
+the website or its workflow, and supports manual dispatch. The workflow will:
+
+1. check out the source;
+2. install the pinned Node.js and package-manager versions;
+3. install dependencies using the lockfile;
+4. build the static site;
+5. upload the generated artifact using `actions/upload-pages-artifact`; and
+6. publish it using `actions/deploy-pages` with only the `pages: write` and
+   `id-token: write` permissions required for deployment.
+
+Pull requests should run the website build as a validation check. Deployment is
+limited to `main`, so a documentation pull request cannot publish production
+content before review and merge.
+
+## Consequences
+
+- Website content, its deployment workflow, and application code stay in one
+  repository and follow the same review, ownership, and history.
+- Contributors primarily write Markdown; VitePress supplies navigation, search,
+  responsive documentation layouts, syntax highlighting, and a small amount of
+  optional Vue-based customization for the landing page.
+- The production site is static, fast, inexpensive, and has no application
+  server or hosting credentials to operate beyond GitHub Pages configuration.
+- The project adds a small Node.js toolchain and lockfile alongside its Go
+  toolchain. The website build must be kept reproducible and updated through
+  normal dependency-review practices.
+- GitHub Pages is appropriate while requirements remain static. Reconsider
+  Cloudflare Pages if the project later needs edge controls, advanced redirects
+  and headers, stronger preview-deployment controls, or broader hosting
+  requirements.
+
+## Alternatives considered
+
+### Docusaurus
+
+Docusaurus is a capable documentation platform with an integrated landing-page
+and blog model. It is a good choice for a large documentation program, but it
+introduces a heavier React-based toolchain than Bible CLI needs initially.
+
+### Hugo
+
+Hugo aligns with the project's Go ecosystem and produces excellent static
+sites. VitePress is preferred for its focused documentation experience and
+straightforward Markdown authoring, without making contributors learn Go
+templates for ordinary documentation changes.
+
+### Cloudflare Pages
+
+Cloudflare Pages is a strong static-hosting option, particularly when advanced
+edge configuration or preview environments are important. GitHub Pages is
+preferred initially because source, review, CI, and publishing stay in the
+repository's existing GitHub workflow.
+
+### Generated files committed to a `gh-pages` branch
+
+Do not commit build output. Publishing an Actions artifact keeps generated
+files out of review history and makes each deployment traceable to its source
+commit and workflow run.

website/.vitepress/config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  lang: "en-US",
+  title: "Bible CLI",
+  description: "Read and search the Bible from your terminal, offline.",
+  base: "/bible-cli/",
+  cleanUrls: true,
+  themeConfig: {
+    nav: [
+      { text: "Guide", link: "/guide/installation" },
+      { text: "Reference", link: "/reference/commands" },
+      { text: "GitHub", link: "https://github.com/vmrocha/bible-cli" }
+    ],
+    sidebar: {
+      "/guide/": [
+        {
+          text: "Guide",
+          items: [
+            { text: "Installation", link: "/guide/installation" },
+            { text: "Reading and search", link: "/guide/reading-and-search" },
+            { text: "Configuration", link: "/guide/configuration" }
+          ]
+        }
+      ],
+      "/reference/": [
+        {
+          text: "Reference",
+          items: [{ text: "Commands", link: "/reference/commands" }]
+        }
+      ]
+    },
+    socialLinks: [{ icon: "github", link: "https://github.com/vmrocha/bible-cli" }],
+    footer: {
+      message: "Released under the MIT License.",
+      copyright: "Copyright © 2026 Bible CLI contributors"
+    },
+    search: { provider: "local" }
+  }
+});

website/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme";
+import "./style.css";
+
+export default DefaultTheme;

website/.vitepress/theme/style.css

@@ -0,0 +1,15 @@
+:root {
+  --vp-c-brand-1: #3f6b4d;
+  --vp-c-brand-2: #568465;
+  --vp-c-brand-3: #78a383;
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: linear-gradient(120deg, #264332, #6d9b79);
+}
+
+.VPHomeHero .text {
+  max-width: 640px;
+}
+
+.VPFeature {
+  border-color: var(--vp-c-divider);
+}

website/guide/configuration.md

@@ -0,0 +1,26 @@
+# Configuration
+
+Bible CLI stores persistent display and translation preferences in a
+versioned JSON file. On macOS and Linux, it resolves the path in this order:
+
+1. `$BIBLE_TERMINAL_CONFIG_HOME/config.json`
+2. `$XDG_CONFIG_HOME/bible-terminal/config.json`
+3. `~/.config/bible-terminal/config.json`
+
+The first two environment variables must be absolute paths.
+
+## Manage preferences
+
+Use the CLI rather than editing the file directly:
+
+```console
+bible config path
+bible config show
+bible config set plain true
+bible config set color false
+bible config set translation webp
+bible config reset
+```
+
+Saved preferences are defaults. Command-line flags always take priority,
+including `--plain=false` and `--no-color=false`.

website/guide/installation.md

@@ -0,0 +1,36 @@
+# Installation
+
+Bible CLI releases are single-binary archives for macOS and Linux on AMD64 and
+ARM64. Downloads include checksums for verification and do not require a
+GitHub account.
+
+## Download a release
+
+1. Open the [latest release](https://github.com/vmrocha/bible-cli/releases/latest).
+2. Download the archive that matches your operating system and architecture.
+3. Verify the archive against `checksums.txt`, then extract it and put `bible`
+   on your `PATH`.
+
+See the repository's [full installation guide](https://github.com/vmrocha/bible-cli/blob/main/docs/INSTALL.md)
+for platform-specific commands, source builds, and checksum verification.
+
+## Confirm the installation
+
+```console
+$ bible version
+$ bible read "John 3:16"
+```
+
+## Shell completion
+
+Generate completion scripts directly from the installed binary:
+
+```console
+bible completion bash
+bible completion zsh
+bible completion fish
+bible completion powershell
+```
+
+The [installation guide](https://github.com/vmrocha/bible-cli/blob/main/docs/INSTALL.md#shell-completion)
+has setup instructions for each shell.

website/guide/reading-and-search.md

@@ -0,0 +1,46 @@
+# Reading and search
+
+Bible CLI accepts common book names and aliases. Quote a reference containing
+punctuation or a verse range so your shell passes it as one argument.
+
+## Read Scripture
+
+```console
+bible read John 3
+bible read "John 3:16"
+bible read "John 3:16-21"
+bible read Jn 3:16 --plain
+```
+
+Move through chapters, including across book boundaries:
+
+```console
+bible read John 3 --next
+bible read Matthew 1 --previous
+```
+
+## Search offline
+
+Search returns verses containing every query token, ranked by relevance with a
+stable canonical order as a tie-breaker.
+
+```console
+bible search "living water"
+bible search "faith hope love" --limit 10
+bible search "kingdom of God" --plain
+```
+
+Punctuation and case do not change matching. A plain search with no matches
+writes no output, making it convenient to compose with other shell tools.
+
+## Output for people and programs
+
+Interactive output uses restrained terminal styling. Redirected output switches
+to plain text automatically; `--plain` and `--no-color` let you choose
+explicitly.
+
+```console
+bible read "Psalm 23"          # styled terminal output
+bible read "Psalm 23" --plain  # stable tab-separated output
+bible read "Psalm 23" | less   # automatically plain
+```

website/index.md

@@ -0,0 +1,37 @@
+---
+layout: home
+
+hero:
+  name: Bible CLI
+  text: Scripture in your terminal.
+  tagline: Read and search the World English Bible offline, with a fast command-line interface that works naturally in shell pipelines.
+  actions:
+    - theme: brand
+      text: Install Bible CLI
+      link: /guide/installation
+    - theme: alt
+      text: Read the guide
+      link: /guide/reading-and-search
+
+features:
+  - title: Offline by default
+    details: Read, navigate, and search the bundled translation without an account, API key, or network connection.
+  - title: Built for the shell
+    details: Human-friendly terminal output becomes stable plain text automatically when redirected or piped.
+  - title: One small binary
+    details: Download a checksummed release for macOS or Linux and start reading without installing Go or a database.
+---
+
+## Start with a passage
+
+```console
+$ bible read "John 3:16-21"
+$ bible search "living water"
+$ bible random
+```
+
+Bible CLI understands common book aliases, lets you navigate between chapters,
+and includes the tools you need to discover books, translations, and shell
+completion.
+
+[View releases on GitHub](https://github.com/vmrocha/bible-cli/releases)