Connect your Git repository
The editor reads and writes Markdown in one folder on disk. If that folder is a Git checkout, the Git actions come alive. If it is not, everything else still works — you simply have no history and nothing to publish.
Point the editor at a checkout
Settings → Workspace → Docs folder holds the path, with a Browse… button beside it. Save settings applies it.
The editor never runs clone or init for you. Create the checkout with your own Git tooling
first — git clone the documentation repository, or git init an existing folder and add a
remote — then point the docs folder at it. Until then the Sync view says No Git repository
yet.
Remote, identity, and credentials
Settings → Collaboration shows what it detected: the remote, the branch, and the name you
will be saving changes as. Two fields are yours to fill in — Your name and Your email,
which become the author and committer on every commit. If the checkout already has user.name
and user.email in its Git config, the editor uses those and you can leave both blank. Without
one or the other, saving a snapshot is refused.
Everything else lives under Advanced (manual overrides):
| Field | What it does |
|---|---|
| Remote URL | Blank uses the folder’s origin |
| Branch | Blank uses the folder’s current branch |
| Username | Paired with an access token over HTTPS |
| Access token | Only for a private remote or HTTPS publishing |
| SSH key path | Only if your key is outside ~/.ssh |
| SSH key passphrase | Only if the key is encrypted and not loaded in an agent |
| Verify SSL | Leave on unless the remote uses a self-signed certificate |
Save Git settings writes them to your OS application-config directory — outside the
checkout, so none of this shows up in git status. Leaving a secret field blank keeps the
stored value rather than clearing it.
HTTPS
Supply Username and Access token. They go out as HTTP basic authentication, sent preemptively. That works with GitHub, GitLab, Gitea, Bitbucket, or any other host — compatibility with the protocol, not an integration with a provider, so there is nothing provider-specific to configure. The token needs read and write on that one repository.
SSH
If the remote URL is an SSH one (ssh://git@host/org/docs.git or git@host:org/docs.git), the
editor uses the keys and known_hosts already in ~/.ssh, exactly as the git command would.
So the host must already be known. For one you have never connected to, do the same one-time
step Git itself requires:
ssh-keyscan gerrit.example.com >> ~/.ssh/known_hosts
An encrypted key that is not loaded in an agent needs the SSH key passphrase field. A key
kept somewhere other than ~/.ssh needs SSH key path.
One remote, one branch
There is a single remote, always origin, and a single tracked branch. The editor never checks
out a different branch — the Branch field only says which branch to fetch and push. Branch
switching stays with your own Git tooling.
What the editor will and will not commit
Two rules, and they matter if your repository holds more than documentation:
- Changes to files Git already tracks are staged, whatever their extension.
- New files are staged only when they end in
.mdor sit under an_attachments/folder.
So a build artefact, a scratch file, or a fresh source file is never swept into a documentation commit. Keeping code and docs in one repository works, as long as you edit the code with your usual tools rather than inside the docs folder.
One rough edge: the changes to publish counter on the Sync view counts every untracked file,
including ones that would never be committed. A .gitignore entry settles it.
Next: Publish and get updates for how those commits reach the team, and Run the server with Docker if you want a read-only web copy of the same repository.