$cat connect/github.md

Connect GitHub.

OAuth · every plan

Edit the markdown that lives in your GitHub repositories — READMEs, docs, notes, anything in a .md file — directly from the MDflow editor. Browse your repos, branches, and folders in the sidebar, open a file, and commit your changes straight back to the repo. No clone, no local checkout, no copy-and-paste.

Once a workspace is connected you can:

›Browse repositories, pick any branch, and open Markdown files in the MDflow editor.
›Edit with live preview, then commit on save with your own message — attributed to your GitHub account.
›Create, rename, and delete Markdown files, each recorded as an ordinary commit.
›Favorite the files you keep returning to, and import any of them into a workspace folder as an ordinary MDflow document.

GitHub integration is free on every plan — no Pro required. Files are read and written live through the GitHub API and are not copied into MDflow unless you import one, so the repository and its git history stay the source of truth.

$why github

Why edit GitHub markdown in MDflow?

›A real editor for your repo docs. Swap GitHub's plain text box for MDflow's Monaco editor — syntax highlighting, live preview, and Edit / Split / Preview views, with the preview following the editor as you scroll.
›The repo stays the source of truth. Nothing is mirrored behind your back. Every save is a real git commit, so your history lives where it always has — and a file only becomes an MDflow document if you import it yourself.
›No local setup. Fix a typo in a README or update your docs from any browser — no clone, no branch juggling, no pushing from the command line.
›Conflict-safe by design. If the file changed on GitHub since you opened it, MDflow warns you and never overwrites silently.
›Free on every plan. Unlike the API and MCP server, GitHub editing needs no Pro subscription.

$prerequisites

Before you start

Field	What to enter
An MDflow account	Any plan — GitHub integration is not Pro-gated. Sign in or sign up.
A GitHub account	The account that owns, or has access to, the repositories you want to edit.
A workspace	You connect GitHub per workspace, so open the workspace you want your repositories to appear in first.

$connect github

Connect your account

Connecting is a one-time, browser-based sign-in — there is no token to create or paste.

Open the workspace menu

In the sidebar, open the menu next to the active workspace name and choose Connect GitHub.

MDflow — workspace menu

Personal

Rename workspace

Edit description

Export workspace

Connect GitHub

Illustration — the workspace actions menu.

Authorize MDflow on GitHub

MDflow sends you to GitHub. Sign in if you are not already, then click Authorize. GitHub hands MDflow an access token scoped to your repositories — see the note below on exactly what that grants.

Land back in your workspace

GitHub returns you to MDflow, and a new GitHub section appears in the sidebar of the connected workspace, below Shared with me. You are ready to browse.

Scope & security: Authorizing grants MDflow the GitHub repo scope — access to the repositories your account can reach — because that is the narrowest scope GitHub offers that can write file contents. MDflow only ever lists your repositories, branches, and files and writes the files you edit. The access token is encrypted at rest, stays on the server, and is never sent to your browser. Disconnecting revokes it.

$edit + commit

Browse, edit, and commit

Open the GitHub section

Expand GitHub in the sidebar. Your repositories are listed newest-push first, with a filter box for long lists. Expand a repository, pick a branch, and drill into its folders — only Markdown files (.md and .markdown) are shown.

MDflow — sidebar

GitHub

filter repositories…

acme/handbookmain ▾

docs/

README.md

CONTRIBUTING.md

Illustration — the GitHub section: filter, repository, branch picker, and Markdown files.

Open a file and edit it

Click any Markdown file to open it in the editor with the usual Edit, Split, and Preview views. The header shows repo / branch / path and links out to the file on GitHub.

Save, then commit

Pressing Save (or ⌘S / Ctrl+S) opens an inline commit bar with an editable message. Confirm it and MDflow commits the change straight to the branch — attributed to your own GitHub account.

mdflow.cz — README.md · acme/handbook@main

# ACME Handbook — your edited markdown…

Commit message

Update README.md

CancelCommit

Illustration — the commit bar shown on save.

If the file changed on GitHub: When someone else commits to the same file after you opened it, MDflow detects the mismatch on save and shows a conflict banner instead of overwriting. Choose Reload from GitHub to pull the latest version, then reapply your edit. Your work is only ever replaced on your explicit choice.

$new · rename · delete

Create, rename, and delete files

›New document — the row menu on a repository or folder creates a new Markdown file there and opens it for editing; the first save is a Create commit.
›Rename — renaming a file moves it to the new path (recorded as a create-and-delete pair of commits).
›Delete — removing a file is a single Delete commit, after a confirmation.

Every change is an ordinary commit on the branch you picked, so it shows up in git log and on GitHub exactly as if you had pushed it yourself.

$how it works

How it works, and what to expect

›A live proxy by default. MDflow reads and writes your files through the GitHub API on demand. A GitHub file enters your MDflow workspace only when you choose Import on it.
›Import is a snapshot, one way. Importing asks which folder of the current workspace to file the copy in, keeps the file name, and hands you an ordinary MDflow document. Editing that copy afterwards changes nothing in the repository, and nothing in the repository changes it.
›Repo features come from git. Because GitHub files themselves are not MDflow documents, MDflow's workspace search, version history, sharing, comments, and offline drafts do not apply to them — their history is the repository's own git history. Favorites are the exception: they are stored by MDflow as a pointer to the repository, branch, and path.
›Existing branches, Markdown only. You edit on any branch that already exists (creating branches and pull requests from MDflow is not part of this version), and only .md / .markdown files up to 500 KB are editable.

Under the hood: Every read and write goes through MDflow's own server to the GitHub API using your authorized token — the browser never sees the token. Commits are made with that token, so GitHub attributes them to your account automatically.

$disconnect github

Disconnect

Open the same workspace menu and choose Disconnect GitHub. MDflow revokes its authorization and removes the connection; your repositories and every commit you made stay exactly as they are. You can also revoke MDflow at any time from GitHub → Settings → Applications.

$man troubleshooting

Troubleshooting

GitHub connection troubleshooting: symptoms and fixes
Symptom	Cause & fix
No GitHub section in the sidebar	It appears only for a workspace that has a connection. Connect from that workspace's menu, or switch to the workspace you connected.
A repository is missing from the list	The list is sorted by most recent push and has a filter box — type part of the `owner/name`. Only repositories your GitHub account can access appear.
A file will not open	Only Markdown files (`.md`, `.markdown`) up to 500 KB are editable. Other file types and larger files are not shown.
`This file changed on GitHub`	Something committed to the file since you opened it. Choose Reload from GitHub to pull the latest, then reapply your edit — MDflow never overwrites silently.
Commits fail / reconnect needed	The GitHub authorization was revoked or expired. Reconnect from the workspace menu (`Connect GitHub`).

./features — everything MDflow does →open MDflow and connect →

> Connect GitHub.