Docs on NookDocs are stored in a Git repository. Most writers use the dashboard editor + never see Git directly — changes save, the site updates, no CLI involved. But when you collaborate with engineers, review a pull request, or hit a merge conflict, understanding Git's model helps.
This guide is the minimum viable Git for writers. No terminal commands. No developer jargon. Just the mental model.
The mental model
Repository = a folder that remembers every change
The docs repo is a folder. Git remembers every version of every file in it — forever. You can always go back.
Commit = a snapshot of all the files, with a note
When you save, you take a "commit" — a frozen copy of every file at that moment, plus a short message explaining what changed.
Branch = a parallel timeline of changes
main is the timeline everyone sees on the live site. You work on a separate "branch" while editing so your changes don't go live until reviewed.
Pull request = 'please merge my branch into main'
When your changes are ready, you open a PR asking teammates to review + merge. The PR shows a diff (what you changed vs what's live).
The three ways changes reach production
Via the dashboard editor (most writers)
Open the editor. Edit a page. Click Save. Behind the scenes, NookDocs commits your change to Git + pushes to the remote. The site updates in ~30 seconds. No branches, no reviews — direct to main.
When to use: small edits, typos, adding a paragraph, no coordination needed.
Via a pull request (reviewed changes)
An engineer opens a branch. They edit files. They push. They open a PR asking for review. A reviewer checks, comments, approves. The PR merges to main. Site updates.
When to use: bigger rewrites, structural changes, anything needing a second pair of eyes.
Via Git directly (engineer-heavy teams)
Clone the repo locally, edit in VS Code, commit, push. Same underlying flow as #2, just without the browser. Faster for power users. When to use: batch edits across 20+ files, or when the dashboard editor doesn't support the workflow.
Most docs sites use a mix — writers live in the dashboard, engineers use Git directly, PRs handle the coordination.
Why branches matter
Without branches, every save goes live immediately. That's fine for a typo fix. Bad for a 3-day rewrite where the page would be half-broken during the work.
Branches let you:
Work for days or weeks without affecting live docs.
Get feedback from teammates BEFORE users see your changes.
Abandon experiments without cleaning up live pages.
Collaborate — two writers working on related pages can each have their own branch.
Rule of thumb: anything over 20 minutes of work wants a branch. Quick fixes can go straight to main via the dashboard.
What a commit looks like
Every commit has three parts:
A diff — which lines in which files were added, removed, or changed.
A message — a short note from the author explaining the "why".
Metadata — who, when, from which parent commit.
Example commit message:
docs(theme): expand theme.mdx from 29 to 177 lines
Added ParamField tables for every color / font / icon token, a
complete example JSON block, precedence rules, dashboard editing
notes. Covers Mintlify parity depth + adds the typography overrides
our multi-theme system supports.Good commit messages have:
A summary line (under 72 chars) — what changed.
A body (optional) — why it changed or context for reviewers.
What a merge conflict is
When two people edit the same lines of the same file and both try to merge, Git doesn't know which version wins. That's a merge conflict.
Example:
Alice edits:
"The feedback widget appears at the bottom of every page."
Bob edits the same line:
"The feedback widget renders under the last article paragraph."When Bob's branch tries to merge and Alice's change is already on main, Git marks the file:
<<<<<<< (Alice's version)
The feedback widget appears at the bottom of every page.
=======
The feedback widget renders under the last article paragraph.
>>>>>>> (Bob's version)Somebody (usually Bob, since he's merging last) has to pick which version stays — or write a third version combining both. After resolving, the merge completes.
Conflicts are normal. Don't panic. If one happens in your PR, ask the engineer who reviewed it for help the first few times.
Git on NookDocs — the hosted flow
NookDocs is a "managed repo" platform — your docs live in a GitHub repository, either in our nookdocs-projects org (managed) or your own. The GitHub App syncs changes automatically:
You save in the dashboard
Dashboard editor commits to your repo via our GitHub App + pushes to main.
Webhook fires
GitHub sends a webhook to NookDocs saying "this repo got a new commit".
Sync job runs
Our Trigger.dev job fetches the new commit, parses MDX, updates the Postgres pages table.
Site updates
Within ~30 seconds of save, the public site serves the new content.
You can also push directly via Git (engineers) — the webhook fires the same way.
Terms you'll see in the dashboard
Commit history — list of all the changes to a page. Click any entry to see the diff.
Last updated — the date of the most recent commit touching this page. Shown at the bottom of every docs page.
Branch selector — which branch the editor is working on (usually
main).Deploy status — did the most recent commit successfully sync to the DB? Green = yes, red = something broke.
When things go wrong
"My change isn't live"
Check the commit landed in the repo. Dashboard Git panel should show your recent change.
Check the deploy status on the project detail page. If red, a sync error happened — open the deployment detail + read the log.
Wait 30-60 seconds. Sync is async; small delay is normal.
Force refresh (Cmd+Shift+R) — your browser might be caching.
"Someone reverted my change"
Not uncommon in team workflows. Check the Git history. If an engineer force-pushed or reverted, they should have left a commit message explaining why. Ask them directly.
"I broke the build"
Parse errors (invalid MDX) block the site deploy. The failed deployment shows which file + what line. Open the file, fix the issue, save again. See maintenance for common MDX issues.
When to ask for help
First merge conflict — always. Conflicts are learnable but easier with someone watching over your shoulder.
Reverting something you didn't mean to commit — Git "reset"/"revert" commands are dangerous. Ask an engineer.
Your PR has 50 comments — step back. Usually means there's a scope problem, not 50 specific fixes. Ask the reviewer for a higher-level call.
What writers don't need to know (but might hear)
Vocabulary you'll encounter but can usually ignore:
Rebase — re-ordering commits. Engineering-level Git surgery.
Cherry-pick — copying specific commits. Niche.
Stash — temporarily shelving uncommitted changes.
HEAD — "where you are right now in the timeline".
Origin / remote — the GitHub-hosted copy of the repo vs your local copy.
Engineers use these routinely. Writers usually don't need to — the dashboard editor abstracts them.
Related
Branches for docs writers — deeper dive into branching strategies for docs teams
Configure automerge — reduce review friction on low-risk changes
Maintenance — Git's role in the freshness audit
Managed repo — NookDocs's hosted GitHub org model
Self-hosted repo — wiring your own repo