Hooks
A hook is a shell command the server runs after a notebook changes: commit it to git, rebuild a website, copy it somewhere. It's set per notebook:
"hook": {
"enabled": true,
"quietSeconds": 60,
"timeoutMinutes": 30,
"runAtStartup": true,
"command": "git add -A && git commit -m {changes} && git push"
}
When it runs
- After a change, the server waits until the notebook has had no changes for
quietSeconds, so a whole sync from a phone gives one run, not dozens. - Only changes to the notebook's content count. Saving a draft, a conflict copy, or emptying the bin doesn't run the hook (publishing, deleting into the bin and restoring do).
- Runs for one notebook never overlap. A change made during a run starts another run afterwards.
- A run taking longer than
timeoutMinutesis killed, with everything it started, so a stuck command (agit pushwaiting for a password) can't stop the hook for good. - With
runAtStartup, it also runs once when the server starts, to catch anything changed while it was stopped (or not hooked because the server crashed).
The command runs with /bin/sh in the notebook's directory. Its output and exit code go to the server's log.
Placeholders
These are replaced in the command, each already quoted for the shell, so write them bare, never inside quotes of your own:
| Placeholder | Becomes |
|---|---|
{notebook} |
The notebook's name. |
{notebookDirectory} |
The notebook's directory. |
{timestamp} |
The time, yyyy-MM-dd HH:mm:ss. |
{changes} |
What changed, e.g. publish food/chili.page (andrew); delete old.page (andrew). For a startup run it's changes while the server was stopped. |
{changedPaths} |
Every path that changed, each quoted separately. |
{users} |
Who made the changes, e.g. andrew,bob. |
Git
Make the notebook a git repository first, with a .gitignore holding .* so drafts, conflict copies and
the bin aren't committed (mdNotebook never touches .git or .gitignore):
cd /path/to/notebook
git init
printf '.*\n!.gitignore\n' > .gitignore
git add -A && git commit -m "Start"
Then the hook:
"command": "rm -f .git/index.lock; git add -A && git commit -q -m {changes} && git push -q"
git add -Aworks out what changed itself, so nothing is missed even after a crash.{changes}is only the description.- Removing
.git/index.lockfirst clears the lock left by a git that was killed part-way. - In Docker, git needs to know who's committing, and (to push) credentials: mount a
.gitconfigand an.sshdirectory read-only into/home/mdnotebook(seecompose.example.yml). The push key must not have a passphrase, because nobody is there to type it. - Anything else the hook runs has to be in the image. The
Dockerfileinstalls git; add whatever else you need there.