From 5c716a3f9b958ddb7c47b7d7481b45a5e50c4e7a Mon Sep 17 00:00:00 2001 From: biosias Date: Sat, 12 Sep 2026 13:14:13 +0200 Subject: [PATCH] Document nginx compression for markdown/JSON transfers (AI) Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01AXSVPS3UmmASiiprPfcnUd --- README.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/README.md b/README.md index 74c4efd..ad52e8b 100644 --- a/README.md +++ b/README.md @@ -362,6 +362,31 @@ server { > `autoindex_format json` is ever lost (config drift, an older nginx), the crawler falls back > to parsing nginx's default HTML directory listing instead of breaking outright. +### Compression + +Markdown and directory-listing JSON are both plain text, so gzip shrinks them well — and since +the browser decompresses transparently, this needs no changes on the cmjs side. nginx doesn't +know `.md` is text by default (it falls back to `application/octet-stream`, which `gzip_types` +won't match), so map it explicitly and enable gzip for both content types: + +```nginx +# in http {} or a shared mime block +types { + text/markdown md; +} + +# in http {} or the server block above +gzip on; +gzip_types text/markdown text/plain application/json; # json covers the autoindex_format listings +gzip_min_length 256; +gzip_vary on; +``` + +Pre-compressing with `gzip_static` is possible but needs a `.md.gz` alongside every article, which +is a build step this project deliberately has none of — plain runtime `gzip on` is the better fit +here. Brotli usually compresses text better still, but needs the separate `ngx_brotli` module, +not built into stock nginx — only worth it if you're already building custom nginx modules. + ## Article discovery & caching Discovery happens in two phases. **Indexing** crawls `cmjs/articles/` client-side to build a