Getting started

ForkLeaf works with no account, no install and no configuration. This page takes you from an empty editor to notes committed in your own GitHub repository, and explains what is happening at each step so nothing about your writing is a mystery.

1. Write something

Open the editor and press New note. You are typing immediately — there is no sign-up wall, because at this point ForkLeaf is not talking to any server at all.

Everything you type is saved to this browser’s IndexedDB within a few hundred milliseconds. The status bar along the bottom of the window tells you so: Saved on this device. Close the tab, kill the browser, lose power — the note is still there when you come back.

2. Sign in with GitHub

Press Continue with GitHub — in the sidebar, in the banner at the top of the editor, or on the landing page. GitHub asks you to authorise ForkLeaf, and you land back in the editor.

Three things happen on that first sign-in:

1. Your access token is encrypted into an httpOnly cookie. It is never sent to the browser as readable JavaScript and never appears in a URL.
2. You land on the dashboard and are asked where your notes should live. Nothing is created on your account until you choose — connect a repository you already have, or have one created for you.
3. Anything you wrote before signing in stays where it is, in local storage, under the On this device workspace. It is not silently uploaded — moving it is your call.

Full detail on the permissions ForkLeaf asks for and why is in Signing in.

3. See your notes on GitHub

This is the part worth checking straight away, because it is the whole premise of the app. Every note has links out to the real thing:

• View notes on GitHub — bottom of the sidebar. Opens the repository.
• Open on GitHub — properties panel on the right, and the GitHub icon in the header. Opens the current note as a file, rendered by GitHub. Your Mermaid diagrams render there too, because they are stored as ordinary ```mermaid fences.
• Version history — properties panel. Every commit that has ever touched this note.
• When each paragraph was written — properties panel. Every paragraph with its date in the margin, shaded by age, and the commit behind whichever one you point at — including what else you changed that day. git blame, for prose: the answer to “when did I learn this, and do I still believe it?”
• Replay how this was written — properties panel, right below it. A chart of the note’s word count across every revision, and a scrubber that plays through them. Useful for the question a commit list cannot answer: whether this page arrived in one sitting or was assembled over a year.
• Publish somewhere else — publish dialog. By default a published page is committed to docs/ in the same repository as your notes, which cannot work when those notes are private: GitHub Pages needs a paid plan for a private repository, and the page would sit inside the repository you were keeping private. Point publishing at a second, public repository instead and the notes stay where they are. One notebook, two audiences, no copy-paste.
• Capture a web page as a source — command palette. Records the address, the moment you read it, and an archived copy from the Wayback Machine, written into the note as an ordinary blockquote. A cited page that later disappears is still readable, which is the difference between a citation and a dead link.
• Link a note to the file it describes — write [[repo:scripts/scan.sh]] to link a file in this repository, or [[repo:you/tools:scripts/scan.sh]] for one in another. Add @a1b2c3d to record the revision you read it at, and the Freshness panel will tell you when that file has changed since — the paragraph describing it is then a paragraph worth re-checking.
• Freshness — properties panel. Whether the note is still true: the files it links that have moved on, and the claims in it that expire — version numbers, CVEs, dates, and sentences hanging on the word “currently” — weighed against how long since you touched it. It never says a note is wrong, only that it is worth re-reading, and always shows why.
• Review & merge this note — properties panel. Propose a note as a pull request, then read the review here instead of on github.com: each comment against the paragraph it was written about, replies in place, and a squash-merge when it is settled. Learning with code review, on your own notes.
• Notes that run — any bash, python or javascript block carries a Run button. The result lands in an ```output block underneath, stamped with when it ran, and commits with the note like anything else — so a runbook records what actually happened instead of what was supposed to. The code runs in a throwaway virtual machine with internet access, never on your own computer, and the machine is destroyed when the run finishes.

You can also just clone it. Nothing about a ForkLeaf repository is special:

git clone https://github.com/you/forkleaf-notes.git
cd forkleaf-notes
ls
# README.md  architecture/  meetings/  reading-list.md

4. Learn the two things worth knowing

The slash key

Type / on an empty line and a menu opens: headings, lists, tables, code blocks, images, and diagrams. This works in all three views — rich text, split and source. If you would rather click, the Insert button on the toolbar has the same list.

The three views

Switching views never rewrites the file. All three are windows onto the same Markdown string, which matters when that string is a commit in your repository.

Where to go next

• How ForkLeaf works — the architecture, in one page.
• Diagrams — the part people underuse.
• Syncing & commits — what the status bar is telling you.