Zettelkasten on GitHub: Linked Notes With Version History

You can keep a Zettelkasten on GitHub as a repository of short Markdown notes connected by relative links. Use stable filenames, precise source references, and small reviewed changes so you can understand both an idea and how it developed. Git records versions; your note structure still has to explain the thinking.

Keep the note collection in the repository. When research affects active work, fenbs can hold the shared project decision and AI handoff alongside links to the relevant notes. A changed file then remains distinguishable from a choice people have accepted for the project.

How do you create a useful note repository?

Begin with one research question and a small folder structure. Markdown is plain text with simple formatting marks, which makes it suitable for readable notes and visible differences between versions. You can start in GitHub’s web interface; a command-line workflow can come later if you need it.

1. Create a repository with a descriptive name and choose its visibility deliberately. Add a README explaining the collection’s purpose and what material belongs there. Follow GitHub’s current repository-creation guide for the interface steps.
2. Create notes and sources folders. Use the first for your own claims and the second for citations and reading notes. Keep an index.md file at the repository root as the entry point.
3. Write one idea in a Markdown file with a stable identifier in its filename. Put the claim in the heading, then explain it, identify the source, and state a limitation.
4. Add a relative link to another relevant note with a sentence explaining the relationship. Link the new note from index.md under the question it helps answer.
5. Save a small change with a message describing the reasoning. Open the rendered files and follow each new link before treating the edit as complete.

GitHub’s repository-creation documentation↗ (opens in a new tab) explains the visibility choice and README options. Start private when material is not approved for publication. A public note collection should contain only content you are permitted to publish, including the quotations and attachments you add.

What structure keeps Markdown notes understandable?

Use filenames that remain stable while your explanation improves. An identifier plus a readable phrase works well, such as 20261021-a-checklist-needs-a-trigger.md. The identifier does not make the idea permanent; it simply reduces the temptation to rename a linked file every time you revise its title.

README.md
index.md
notes/
  20261021-a-checklist-needs-a-trigger.md
  20261021-instructions-need-a-reader.md
sources/
  onboarding-observation.md

The README explains how to use and contribute to the collection. The index organizes entry points by questions, while source notes preserve the evidence behind your interpretations. Avoid a separate folder for every overlapping subject; a note can be relevant to several questions through links.

This is one way to organize reusable understanding, within the broader second-brain collection. The repository does not need to become a publishing system or software project before the notes become useful.

What should the note template include?

A short template helps contributors preserve the difference between evidence and interpretation. The following fictional example uses a local source note and a related idea. Replace the example with a claim you can support, rather than retaining empty headings just to satisfy the format.

# A checklist needs a clear starting condition

A reader may understand the actions but still not know when to
start them. State the event that triggers the checklist.

## Evidence
Source: [Onboarding observation](../sources/onboarding-observation.md),
exercise 3. This is an interpretation of one exercise.

## Connections
This extends [Instructions need a reader](20261021-instructions-need-a-reader.md):
the reader needs both an action and the condition for taking it.

## Open question
Would the revised starting condition help in a second exercise?

GitHub’s Markdown syntax guide↗ (opens in a new tab) recommends relative links between repository files and explains that their paths are relative to the current file. Test from the rendered note, because a path that works in the root index may need ../ when used inside notes.

How do you review changes without losing the reasoning?

Keep each change focused on one improvement: adding an idea, correcting an interpretation, or repairing links after a deliberate move. Write why the change matters in its message. A history full of “update notes” entries can show that something changed without explaining what a future reader should learn from it.

For shared collections, propose substantive edits through a pull request, a request to review and merge a set of changes. GitHub’s pull-request documentation↗ (opens in a new tab) describes the conversation and file-difference views. Ask reviewers to check the evidence and the claim’s scope, as well as grammar and formatting.

• Does the source support the exact wording of the claim?
• Are quotations distinguished from the contributor’s interpretation?
• Do new links explain a relationship instead of only matching a subject?
• Did the edit introduce broken paths or material that should remain private?

When an interpretation changes, preserve its reason in the edit rather than pretending the earlier version never existed. GitHub’s file-viewing guide↗ (opens in a new tab) explains how Blame connects lines to the commits that last changed them. Version history helps trace wording; a project’s current decision still needs an explicit record.

How can an assistant help without making notes look verified?

Give the assistant a narrow assignment, such as proposing missing connections among three named notes. Require a sentence explaining each suggestion and a reference to the supplied evidence. Keep proposed notes separate until a person reviews them; fluent prose does not establish that a source supports the claim.

If you choose a repository assistant, the guides to the GitHub Copilot app, GitHub Copilot CLI, and GitHub Copilot hooks cover those separate setup questions. You can maintain this note system without adopting an assistant or adding automation.

After review, record which conclusion the project accepted and what still needs investigation. That work belongs with fenbs project context and Decisions and rules, so a later assistant can distinguish a research possibility from the direction a person chose.

How to do this with fenbs

1. Create a free account and add the project using the note collection.
2. Add descriptive links to the relevant notes in Links and listings. Record the source location or version you reviewed when the wording matters to a decision.
3. Save a context note with the accepted finding, its limits, and any conflicting evidence. Put a person’s project choice in Decisions and rules.
4. Connect a supported assistant through Integrations. Ask it to read the project context before working and save progress with the reviewed notes, unfinished checks, and next step.

fenbs is free for one person, with no credit card. It does not mirror your GitHub repository or import notes automatically. If your only need is a personal note collection with version history, GitHub may be enough; fenbs helps when people or assistants need a maintained project record across sessions.

Test one transition before expanding the setup. Ask the next assistant to identify the accepted conclusion, the evidence it used, and the remaining question from the saved record. The AI handoff workflow explains how to make that a normal part of stopping and restarting work.