diff --git a/.gitignore b/.gitignore
index 439dc65..6d2b586 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1 +1,2 @@
 /articles/
+/js/config.js
diff --git a/README.md b/README.md
index c636baa..5a8261b 100644
--- a/README.md
+++ b/README.md
@@ -58,7 +58,8 @@ from the library — not something an embedding page needs to bring along.
 │       ├── toc.css             # Auto-generated table of contents
 │       └── author-profile.css  # Author profile card (avatar, bio, social links)
 ├── js/
-│   ├── config.js       # BASE_URL, MARKED_URL, ARTICLES_URL (all via import.meta.url)
+│   ├── config-default.js  # Shipped defaults for BASE_URL, MARKED_URL, ARTICLES_URL
+│   ├── config.js       # Your local overrides — gitignored; see "Local configuration" below
 │   ├── frontmatter.js  # parseFrontmatter() — pure YAML-front parser
 │   ├── templates.js    # loadTemplates(), templates cache
 │   ├── discovery.js    # discoverArticles(), fetchJson(), article cache
@@ -86,6 +87,31 @@ from the library — not something an embedding page needs to bring along.
         └── slug~DDMMYYYY~tag1+tag2.md         # One file per article — see "Adding an article"
 ```
 
+## Local configuration
+
+**Before first use, create your own `js/config.js`** — it doesn't ship with the repo (it's
+gitignored) and nothing works without it:
+
+```bash
+cp js/config-default.js js/config.js
+```
+
+`js/config-default.js` holds the shipped defaults (`BASE_URL`, `MARKED_URL`, `ARTICLES_URL`) and
+is tracked in git; every other module imports from `js/config.js` instead, which by default just
+re-exports those defaults unchanged. The split exists for using cmjs as a git submodule (or
+otherwise pulling in a newer version some other way): since `config.js` is gitignored, updating
+cmjs never overwrites it, so any local overrides you've made survive the update. Only
+`config-default.js` gets updated.
+
+To override a setting, re-export the rest from `config-default.js` and define your own instead —
+e.g. to move where articles live (see "Pointing articles/ somewhere else" below for the matching
+nginx-side change this needs):
+
+```js
+export { BASE_URL, MARKED_URL } from './config-default.js';
+export const ARTICLES_URL = new URL('/blog-content/articles/', location.origin).href;
+```
+
 ## Adding an article
 
 An article is a single Markdown file placed directly in its author's directory. Its *file name*
@@ -254,6 +280,9 @@ translate it by editing that page directly (`demo/index.html` for this repo's ow
 
 ## Embedding in an existing page
 
+Make sure you've done the one-time setup in "Local configuration" above (`cp js/config-default.js
+js/config.js`) wherever you place these files — nothing loads without it.
+
 To add cmjs to any HTML page, three things are needed: the CSS, the two mount-point `<div>`s, and the script.
 
 ### 1. CSS — in `<head>`
@@ -393,14 +422,10 @@ server {
 
 ### Pointing articles/ somewhere else
 
-By default the crawler looks for articles at `articles/` next to the rest of cmjs (`ARTICLES_URL`
-in `js/config.js`, computed as a sibling of the `js/` folder). Articles don't have to live there —
-edit `ARTICLES_URL` in `js/config.js` to point anywhere under the same origin (or a different one,
-CORS permitting), e.g.:
-
-```js
-export const ARTICLES_URL = new URL('/blog-content/articles/', location.origin).href;
-```
+By default the crawler looks for articles at `articles/` next to the rest of cmjs (`ARTICLES_URL`,
+computed as a sibling of the `js/` folder). Articles don't have to live there — override
+`ARTICLES_URL` in your local `js/config.js` (see "Local configuration" above) to point anywhere
+under the same origin (or a different one, CORS permitting).
 
 Whatever it resolves to needs its own matching `location` block enabling the JSON (or HTML)
 autoindex — it doesn't have to be named `articles/` or nested under wherever cmjs itself lives:
@@ -504,6 +529,9 @@ of content is ever fetched per page view.
 
 ## Running locally
 
+Don't forget the one-time setup step in "Local configuration" above (`cp js/config-default.js
+js/config.js`) — nothing loads without it.
+
 Using nginx locally (example for Linux):
 ```bash
 # Symlink or copy the repo to your nginx webroot, then reload:
diff --git a/js/config.js b/js/config-default.js
similarity index 68%
rename from js/config.js
rename to js/config-default.js
index ff3405b..4b8e980 100644
--- a/js/config.js
+++ b/js/config-default.js
@@ -1,5 +1,14 @@
 // All paths are derived from this module's own location via import.meta.url,
 // so they resolve correctly regardless of where the embedding HTML page lives.
+//
+// This file ships with cmjs and is tracked in git — don't edit it directly.
+// Everything else imports from the sibling `config.js` instead (gitignored,
+// not part of this repo's history), which re-exports these defaults as-is
+// unless overridden. That split means your own overrides (e.g. a custom
+// ARTICLES_URL) survive updating cmjs — as a git submodule or by any other
+// means of pulling in a newer version — since a fresh copy of this file
+// never touches your untracked config.js. See "Local configuration" in the
+// README.
 
 // Base URL of the repo root — strings/ and templates/ live here, one level
 // up from this file (e.g. https://example.com/).