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 timeoutMinutes is killed, with everything it started, so a stuck command (a git push waiting 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 -A works out what changed itself, so nothing is missed even after a crash. {changes} is only the description.
  • Removing .git/index.lock first 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 .gitconfig and an .ssh directory read-only into /home/mdnotebook (see compose.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 Dockerfile installs git; add whatever else you need there.