Skip to content

Commit 0ea3755

Browse files
sspaetisspaeti
committed
adding docs with Hugo hextra Template
1 parent 562f52d commit 0ea3755

33 files changed

Lines changed: 833 additions & 37 deletions

‎.claude/settings.local.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,12 @@
55
"Bash(go test:*)",
66
"Bash(make build:*)",
77
"Bash(make test:*)",
8-
"WebFetch(domain:www.ssp.sh)"
8+
"WebFetch(domain:www.ssp.sh)",
9+
"Bash(make docs-build:*)",
10+
"Bash(hugo version:*)",
11+
"Bash(hugo mod graph:*)",
12+
"Bash(make docs-sync:*)",
13+
"WebFetch(domain:raw.githubusercontent.com)"
914
]
1015
}
1116
}

‎.github/workflows/deploy-docs.yaml‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Deploy Hugo documentation site to GitHub Pages
2+
name: Deploy Documentation
3+
4+
on:
5+
# Runs on pushes targeting the main branch
6+
push:
7+
branches: ["main", "neomd-docs"]
8+
paths:
9+
- 'docs/**'
10+
- '.github/workflows/deploy-docs.yaml'
11+
12+
# Allows you to run this workflow manually from the Actions tab
13+
workflow_dispatch:
14+
15+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
16+
permissions:
17+
contents: read
18+
pages: write
19+
id-token: write
20+
21+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
22+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
23+
concurrency:
24+
group: "pages"
25+
cancel-in-progress: false
26+
27+
# Default to bash
28+
defaults:
29+
run:
30+
shell: bash
31+
32+
jobs:
33+
# Build job
34+
build:
35+
runs-on: ubuntu-latest
36+
env:
37+
HUGO_VERSION: 0.156.0
38+
steps:
39+
- name: Checkout
40+
uses: actions/checkout@v4
41+
with:
42+
fetch-depth: 0 # fetch all history for .GitInfo and .Lastmod
43+
submodules: recursive
44+
45+
- name: Setup Go
46+
uses: actions/setup-go@v5
47+
with:
48+
go-version: '1.24'
49+
50+
- name: Setup Pages
51+
id: pages
52+
uses: actions/configure-pages@v4
53+
54+
- name: Setup Hugo
55+
run: |
56+
wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
57+
&& sudo dpkg -i ${{ runner.temp }}/hugo.deb
58+
59+
- name: Build with Hugo
60+
env:
61+
# For maximum backward compatibility with Hugo modules
62+
HUGO_ENVIRONMENT: production
63+
HUGO_ENV: production
64+
run: |
65+
cd docs
66+
hugo \
67+
--gc --minify \
68+
--baseURL "${{ steps.pages.outputs.base_url }}/"
69+
70+
- name: Upload artifact
71+
uses: actions/upload-pages-artifact@v3
72+
with:
73+
path: ./docs/public
74+
75+
# Deployment job
76+
deploy:
77+
environment:
78+
name: github-pages
79+
url: ${{ steps.deployment.outputs.page_url }}
80+
runs-on: ubuntu-latest
81+
needs: build
82+
steps:
83+
- name: Deploy to GitHub Pages
84+
id: deployment
85+
uses: actions/deploy-pages@v4

‎Makefile‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,9 @@ LDFLAGS := -ldflags "-X main.version=$(VERSION)"
66

77
.PHONY: build run install clean test test-integration send-test vet fmt tidy release docs help check-go demo demo-reset demo-hp demo-hp-reset benchmark
88

9+
10+
.DEFAULT_GOAL := install
11+
912
## check-go: verify Go is installed
1013
check-go:
1114
@command -v go >/dev/null 2>&1 || { \
@@ -110,7 +113,7 @@ clean:
110113
rm -f $(BINARY) $(BINARY)-android
111114

112115
## release: tag and push a new release (usage: make release VERSION=v0.1.0)
113-
release: docs
116+
release: docs docs-build
114117
@test -n "$(VERSION)" || (echo "Usage: make release VERSION=v0.1.0" && exit 1)
115118
git tag -a $(VERSION) -m "Release $(VERSION)"
116119
git push origin $(VERSION)
@@ -119,6 +122,23 @@ release: docs
119122
## docs: regenerate keybindings section in README.md from internal/ui/keys.go
120123
docs:
121124
go run ./cmd/docs
125+
@./scripts/sync-readme-to-docs.sh
126+
127+
## docs-sync: sync README.md to docs/content/overview.md
128+
docs-sync:
129+
./scripts/sync-readme-to-docs.sh
130+
131+
## docs-serve: serve Hugo docs site locally at http://localhost:1313
132+
docs-serve:
133+
$(MAKE) -C docs serve
134+
135+
## docs-build: build Hugo docs site to docs/public/
136+
docs-build:
137+
$(MAKE) -C docs build
138+
139+
## docs-clean: remove generated Hugo files
140+
docs-clean:
141+
$(MAKE) -C docs clean
122142

123143
## help: print this list
124144
help:

‎cmd/docs/main.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// docs regenerates the keybindings section in docs/keybindings.md from the
1+
// docs regenerates the keybindings section in docs/content/docs/keybindings.md from the
22
// single source of truth in internal/ui/keys.go.
33
//
44
// Usage: go run ./cmd/docs (or: make docs)
@@ -17,7 +17,7 @@ import (
1717
)
1818

1919
const (
20-
readmePath = "docs/keybindings.md"
20+
readmePath = "docs/content/docs/keybindings.md"
2121
startTag = "<!-- keybindings-start -->"
2222
endTag = "<!-- keybindings-end -->"
2323
)

‎docs/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Hugo build artifacts
2+
public/
3+
resources/
4+
.hugo_build.lock

‎docs/Makefile‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.PHONY: serve build clean help
2+
3+
.DEFAULT_GOAL := serve
4+
5+
## serve: serve Hugo docs site locally at http://localhost:1313
6+
serve:
7+
@echo "Starting Hugo development server..."
8+
hugo server -D --port 1311
9+
10+
## build: build Hugo docs site to public/
11+
build:
12+
@echo "Building Hugo docs site..."
13+
hugo --gc --minify
14+
15+
## clean: remove generated files
16+
clean:
17+
@echo "Cleaning generated files..."
18+
rm -rf public resources .hugo_build.lock
19+
20+
## help: print this list
21+
help:
22+
@grep -E '^## ' Makefile | sed 's/^## //'

‎docs/content/_index.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: neomd
3+
layout: hextra-home
4+
toc: false
5+
---
6+
7+
<div class="hx-mt-6 hx-mb-6">
8+
{{< hextra/hero-headline >}}
9+
A minimal terminal email client&nbsp;<br class="sm:hx-block hx-hidden" />for people who read & write in Markdown
10+
{{< /hextra/hero-headline >}}
11+
</div>
12+
13+
<div class="hx-mb-12">
14+
{{< hextra/hero-subtitle >}}
15+
Compose in Neovim, navigate with Vim motions, screen emails like HEY,&nbsp;<br class="sm:hx-block hx-hidden" />process your inbox with GTD — all from the terminal
16+
{{< /hextra/hero-subtitle >}}
17+
</div>
18+
19+
<div class="hx-mb-6">
20+
{{< hextra/hero-button text="Overview and Philosophy" link="docs/overview" >}}
21+
</div>
22+
23+
<div class="hx-mt-6"></div>
24+
25+
<div class="hx-mt-12 hx-mb-8">
26+
<h2 class="hx-text-4xl hx-font-bold hx-tracking-tight hx-text-gray-900 dark:hx-text-gray-50">What Makes neomd Different?</h2>
27+
</div>
28+
29+
{{< hextra/feature-grid >}}
30+
{{< hextra/feature-card
31+
title="HEY-Style Screener"
32+
subtitle="Unknown senders wait in ToScreen until you approve (I), block (O), or categorize them. You choose who reaches your inbox — bye-bye spam."
33+
class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
34+
style="background: radial-gradient(ellipse at 50% 80%,rgba(1,97,254,0.15),hsla(0,0%,100%,0));"
35+
>}}
36+
{{< hextra/feature-card
37+
title="GTD Workflow"
38+
subtitle="Process your inbox only once. Move emails to Waiting, Someday, Scheduled, or Archive with single keystrokes. Includes Feed and PaperTrail for newsletters and receipts."
39+
class="aspect-auto md:aspect-[1.1/1] max-lg:min-h-[340px]"
40+
style="background: radial-gradient(ellipse at 50% 80%,rgba(194,97,254,0.15),hsla(0,0%,100%,0));"
41+
>}}
42+
{{< hextra/feature-card
43+
title="Superhuman Speed"
44+
subtitle="Folder switches in ~33ms (on fast IMAP providers like Hostpoint). Every action is instant — no loading spinners, no delays. Navigate with Vim motions."
45+
class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
46+
style="background: radial-gradient(ellipse at 50% 80%,rgba(142,53,74,0.15),hsla(0,0%,100%,0));"
47+
>}}
48+
{{< hextra/feature-card
49+
title="Neovim Integration"
50+
subtitle="Compose in $EDITOR (nvim), send as Markdown → HTML multipart. Pre-send review prevents accidental sends. Auto-backup drafts to ~/.cache."
51+
class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
52+
style="background: radial-gradient(ellipse at 50% 80%,rgba(12,53,74,0.15),hsla(0,0%,100%,0));"
53+
>}}
54+
{{< hextra/feature-card
55+
title="Direct IMAP/SMTP"
56+
subtitle="No local sync daemon. Uses RFC 6851 MOVE for instant operations. Works on any device with your mailbox always in sync."
57+
class="aspect-auto md:aspect-[1.1/1] max-lg:min-h-[340px]"
58+
style="background: radial-gradient(ellipse at 50% 80%,rgba(221,210,59,0.15),hsla(0,0%,100%,0));"
59+
>}}
60+
{{< hextra/feature-card
61+
title="Keyboard-First"
62+
subtitle="Vim motions everywhere. j/k navigation, gg/G jumps, / search, numbered links [1]-[0], multi-select with m, undo with u."
63+
class="aspect-auto md:aspect-[1.1/1] max-md:min-h-[340px]"
64+
style="background: radial-gradient(ellipse at 50% 80%,rgba(59,130,246,0.15),hsla(0,0%,100%,0));"
65+
>}}
66+
{{< /hextra/feature-grid >}}
67+
68+
<br>
69+
70+
<div class="hx-mt-12 hx-mb-8">
71+
<h2 class="hx-text-4xl hx-font-bold hx-tracking-tight hx-text-gray-900 dark:hx-text-gray-50">Video Demo</h2>
72+
</div>
73+
74+
YouTube rundown of most features:
75+
[![neomd demo](https://img.youtube.com/vi/lpmHqIrCC-w/maxresdefault.jpg)](https://youtu.be/8aKkldYLWV8)
76+
77+
78+
<div class="hx-mt-12 hx-mb-8">
79+
<h2 class="hx-text-4xl hx-font-bold hx-tracking-tight hx-text-gray-900 dark:hx-text-gray-50">Documentation</h2>
80+
</div>
81+
82+
{{< cards cols="3" >}}
83+
{{< card link="docs/overview" title="Overview & Philosophy" subtitle="Full feature list, installation (binary, AUR, source), philosophy, benchmarks, and inspiration" >}}
84+
{{< card link="docs/configuration" title="Configuration Reference" subtitle="Full config with multiple accounts, OAuth2, signatures, and UI options" >}}
85+
{{< card link="docs/keybindings" title="Keybindings" subtitle="Complete keyboard shortcuts reference (auto-generated from source)" >}}
86+
{{< card link="docs/screener" title="Screener Workflow" subtitle="How to classify emails, bulk operations, and screener lists" >}}
87+
{{< card link="docs/reading" title="Reading Emails" subtitle="Navigation, images, links, attachments, threading" >}}
88+
{{< card link="docs/sending" title="Sending Emails" subtitle="Compose, attachments, CC/BCC, drafts, HTML signatures" >}}
89+
{{< /cards >}}
90+
91+
<br>
92+
93+
<div class="hx-mb-6">
94+
{{< hextra/hero-button text="Getting Started: Install" link="docs/overview#install" >}}
95+
</div>
96+
97+
98+
<div class="hx-mt-12 hx-mb-8">
99+
<h2 class="hx-text-4xl hx-font-bold hx-tracking-tight hx-text-gray-900 dark:hx-text-gray-50">Links</h2>
100+
</div>
101+
102+
- [GitHub Repository](https://github.com/ssp-data/neomd)
103+
- [Changelog](https://github.com/ssp-data/neomd/blob/main/CHANGELOG.md)
104+
- [Roadmap](https://www.ssp.sh/brain/neomd#roadmap)
105+
- [Security Policy](https://github.com/ssp-data/neomd/blob/main/SECURITY.md)

‎docs/content/docs/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: Documentation
3+
---
4+
5+
Welcome to the neomd documentation.

docs/configuration.md renamed to docs/content/docs/configuration.md

Lines changed: 14 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# Configuration Reference
1+
---
2+
title: Configuration Reference
3+
weight: 1
4+
---
25

36
On first run, neomd creates `~/.config/neomd/config.toml` with placeholders.
47

@@ -64,7 +67,7 @@ spam = "spam" #check capitalization of your pre-existing Spam folder, so
6467
# work = "Work" # optional custom folder; add "work" to tab_order to show as a tab (gb to go, Mb to move -b for business as w was taken)
6568
# tab_order controls the left-to-right tab sequence; omit to use the built-in default order. e.g.:
6669
# tab_order = ["inbox", "to_screen", "feed", "papertrail", "waiting", "someday", "scheduled", "sent", "archive", "screened_out", "drafts", "trash"]
67-
# Gmail uses different folder names — see docs/gmail.md for the correct mapping.
70+
# Gmail uses different folder names — see docs/content/gmail.md for the correct mapping.
6871

6972
[ui]
7073
theme = "dark" # dark | light | auto
@@ -82,14 +85,15 @@ Connect: [LinkedIn](https://example.com/)
8285
```
8386

8487

85-
> [!NOTE]
86-
> **Gmail** uses different IMAP folder names (`[Gmail]/Sent Mail`, `[Gmail]/Trash`, etc.). See [Gmail Configuration](gmail.md) for the correct mapping.
88+
{{< callout type="info" >}}
89+
**Gmail** uses different IMAP folder names (`[Gmail]/Sent Mail`, `[Gmail]/Trash`, etc.). See [Gmail Configuration](configurations/gmail) for the correct mapping.
90+
{{< /callout >}}
8791

8892
Use an app-specific password (Gmail, Fastmail, Hostpoint, etc.) rather than your main account password.
8993

9094
`inbox_count` is a fetch cap for normal folder loads and startup auto-screening. If you want to re-screen the entire Inbox on the IMAP server, use `:screen-all` from inside neomd; that scans every Inbox email, not just the loaded subset, and can take a while on large mailboxes.
9195

92-
### Environment Variables
96+
## Environment Variables
9397

9498
The `password` and `user` fields support environment variable expansion. If the entire value is a single env var reference, neomd resolves it at startup:
9599

@@ -102,7 +106,7 @@ Values containing other text or multiple `$` signs are left as-is, so passwords
102106

103107
Credentials are stored only in `~/.config/neomd/config.toml` (mode 0600) and never written elsewhere; all IMAP connections use TLS (port 993) or STARTTLS (port 143).
104108

105-
### TLS and STARTTLS Configuration
109+
## TLS and STARTTLS Configuration
106110

107111
Neomd automatically determines the correct encryption method based on the port and the optional `starttls` config field:
108112

@@ -146,15 +150,15 @@ smtp = "mail.custom.com:2587"
146150
starttls = true # Forces STARTTLS instead of TLS
147151
```
148152

149-
See `docs/proton-bridge.md` for complete Proton Mail Bridge setup instructions.
153+
See [Proton Bridge Setup](configurations/proton-bridge) for complete Proton Mail Bridge setup instructions.
150154

151155
For localhost/self-signed bridges such as Proton Mail Bridge, neomd first tries
152156
normal certificate verification. If that fails with an unknown-authority error
153157
on a loopback host (`127.0.0.1`, `::1`, `localhost`), neomd retries once with a
154158
localhost-only fallback so existing Bridge setups keep working. If you want
155159
strict verification, export the Bridge certificate and set `tls_cert_file`.
156160

157-
### Sent and Drafts Storage
161+
## Sent and Drafts Storage
158162

159163
When multiple accounts or `[[senders]]` aliases are configured, SMTP delivery
160164
always uses the selected sending identity's account.
@@ -223,7 +227,7 @@ For professional HTML signatures (with logos, tables, styled text), use the `[ui
223227
#### This is how it looks
224228

225229
The sent e-mail with above HTML signature looks like this:
226-
![image](../images/html-signature.png)
230+
![HTML signature example](/images/html-signature.png)
227231

228232
In the email as text:
229233
```markdown
@@ -233,7 +237,7 @@ how are you
233237
here's my new HTML signature below.
234238
BR Simon
235239

236-
--
240+
--
237241
[html-signature]
238242
```
239243

‎docs/content/docs/configurations/_index.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
title: Platform Guides
3+
weight: 50
4+
sidebar:
5+
open: false
6+
---
7+
8+
Provider-specific configuration guides for Gmail, Proton Mail, and Android/Termux.

0 commit comments

Comments
 (0)