Clew — website and manual
The public documentation for Clew: a landing page and a 28-chapter manual,
served as one static tree.
Live at https://clew-app.com — or it will be: the domain is registered
but still on the registrar's parking IPs. See
First-time server setup.
clew-app.net is registered too and redirects to .com, so the two do not
become separately-indexed copies of the same site.
This is a sibling of Clew-app and Clew-iOS under ~/Source/Clew/, and it is
its own git repository. The docs describe Clew, not the desktop app
specifically, so they belong beside both implementations rather than inside
either one.
Layout
site/ ← the web root; everything here is published
├── index.html landing page
├── images/ landing-page art + the app icon (see below)
├── manual/ the manual: 34 chapters + index
│ ├── manual.css shared stylesheet (landing-page palette)
│ ├── nav.js single source of the sidebar tree and prev/next links
│ ├── lightbox.js click a screenshot to see it large (+ lightbox.css);
│ │ the landing page loads these too
│ └── images/ the manual's own copy of every screenshot
└── downloads/ release binaries — not in git, staged from Clew-app/out/
check-links.js link checker: `make check-links`
apply-og.js regenerates the manual's social tags: `make og-tags`
stamp-assets.js puts content hashes in CSS/JS URLs: `make stamp`
shots/ recipes for the app screenshots (see shots/README.md)
og/clew-og.html source of the social card: `make og-card`
clew-app.com.nginx.conf the server config, mirrored on the droplet at
/etc/nginx/sites-available/clew-app.com
Makefile deployment; `make help` lists the targets
CLAUDE.md guidance for Claude Code, including the editing conventions
HANDOVER.md session state and open items — read this first
Nothing outside site/ is ever published. That is the whole reason for the
extra directory level: the deploy is a directory sync, so anything that must
not reach the web has to be somewhere the sync cannot see.
The manual is self-contained on purpose
site/manual/images/ duplicates ten files from site/images/. Keep the
duplication. The manual is sometimes served as its own web root, and every
../images/ reference 404s the moment it is. make check-links fails the
build if a manual page reaches above manual/ for an asset.
The one deliberate exception is the top bar's Home and Download links, which
point at ../index.html. Those are navigation rather than assets, they are
expected to leave the manual, and check-links reports them as a counted
note rather than an error.
Screenshots zoom; CSS and JS URLs carry their hash
A screenshot is written wrapped in a link to its own file —
<figure class="shot"><a class="zoom" href="images/x.png"><img …></a> in
the manual, <a class="zoom" href="images/x.jpg"><img class="shot" …></a>
on the landing page. lightbox.js turns a plain click on one into a modal
viewer (Esc, the ×, or a click outside closes it; ← and → step through the
page's screenshots); a middle-click, a new tab, or a browser without
scripts follows the link to the picture instead. Decoration — the brand
icon — is never wrapped, and so never zooms. Wrap every new screenshot
the same way.
nginx gives CSS and JS a 7-day expiry, so every <link> and <script>
URL carries ?v= and the file's content hash. After editing
manual.css, nav.js or lightbox.*, run make stamp; make check-links fails on a stamp that no longer matches its file.
Social previews
Every page carries Open Graph and Twitter card tags, so a shared link renders
as a card rather than a bare URL. Two moving parts:
The image — site/images/clew-og-card.jpg, 1200×630, generated from
og/clew-og.html by make og-card. It is HTML rather than a drawing so the
wordmark, palette and tagline cannot drift from the landing page. Rendered
with headless Chrome at 2× and downsampled by sips; both ship with macOS, so
unlike the og-renderer used by the other sites this needs no puppeteer, no
sharp, and no node_modules.
Must be re-rendered on a Mac. The card asks for Avenir Next, the same face
the landing page asks for first. Anywhere else it silently falls back and the
wordmark comes out in Helvetica.
The tags — the landing page's are hand-written and describe the site. The
manual's 28 pages get theirs from make og-tags, derived from each page's own
<title> and <meta name="description"> so there is one source for a page's
description rather than two that can disagree.
Run make og-tags after adding a chapter. A chapter written by copying an
existing page inherits its og:url and og:title, and nothing about the
rendered page looks wrong — the tags are invisible until someone shares the
link, at which point the new chapter claims to be the old one. make check-links reports any page whose og:url disagrees with its filename.
If the domain ever changes, it appears in apply-og.js (SITE), in
site/index.html, and in og/clew-og.html's footer.
Deploying
make dry-run # see exactly what would change
make sync # upload site/ (not the binaries)
sync uses rsync --delete, so a page removed here is removed from the
server — that is how a renamed chapter stops answering at its old URL. It also
means a truncated local tree would erase the live site, so make check
(which sync depends on) refuses to run unless the landing page, the manual
index, and at least 50 files are all present.
site/downloads/ is excluded from that sync, which both keeps 640 MB off the
wire on every ordinary deploy and protects the remote copy from --delete.
여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗
