Donut is a Personal Knowledge Management (PKM) tool combining zettelkasten style of knowledge capture with spaced repetition and recall, and the ability to share knowledge bits with other people (for buddies and teams).
For more background info you can read::
# Install (macOS, Linux, WSL)
curl https://doughnut.odd-e.com/install -fsS | bash
# Install (Windows PowerShell)
irm 'https://doughnut.odd-e.com/install?win32=true' | iex
# Run CLI
donutdonut notebook publish <directory> publishes the checkout's committed main.
If the checkout has staged, unstaged, or untracked work, the command warns that
those local changes are excluded and leaves them untouched. donut notebook pull <directory> changes the checkout and therefore still requires a clean
local main. Web edits to an existing note append the notebook's accepted Git
history. After a web title change, pull fast-forwards that history, replaces the
old Markdown path with the title-derived path, and keeps the checkout clean.
Format changed components explicitly before staging:
./scripts/run.sh pnpm format:changed
git add <intended-paths>
git commit -m "..."format:changed considers staged, unstaged, and nonignored untracked paths,
then formats only the affected repository components. Review those changes
before staging the intended commit.
A pre-commit hook then validates affected staged components with
pnpm lint:changed. It is check-only: it does not format files or mutate the
working tree or Git index.
Setup:
The git hooks are version-controlled in scripts/git-hooks/. To install them, run:
./scripts/setup-git-hooks.shThis will copy the hooks from scripts/git-hooks/ to .git/hooks/ and make them executable. You only need to run this once after cloning the repository, or whenever hooks are updated.
Behavior:
- The hook runs automatically on every
git commit - It lints only the components affected by staged paths
- If linting succeeds, the commit proceeds
- If linting fails, the commit is blocked without staging or rewriting files
Note: The hook uses ./scripts/run.sh which automatically handles the nix environment, so it works whether you're in a nix shell or not.
You can find the database migrations in backend/src/main/resources/db/migration/.
The migrations are run automatically when the backend app starts up.
It will also run the migrations for test when you run pnpm backend:test.
To trigger the test DB migration manually, run backend/gradlew migrateTestDB.
To connect to the local DB: mysql -S $MYSQL_HOME/mysql.sock -u doughnut -p (password=doughnut).
pnpm backend:test and migrateTestDB use the shared doughnut_test database.
For a checkout-local test database (Git worktrees), see isolated backend tests.
We chose Vue3 + Vite to build our frontend.
The TypeScript code calling the backend services is generated from the backend code. Run
pnpm generateTypeScriptTo do the code generation. There are two steps in this command:
- Generate openAPI docs from the backend service into
./open_api_docs.yaml. - Generate TypeScript interfaces from the openAPI docs, into
frontend/src/generated.
If the step 1 is not done, a unit test will fail. If the step 2 is not done, CI will fail (./assert_generated_type_script_up_to_date.sh).
From doughnut source root directory
pnpm frontend:verifyRun frontend dev server only (Vite; see prod_env.md for the full stack)
pnpm frontend:sutBuild & Bundle Vue3 frontend web-app assets and startup backend app (backend webapp will launch on port 9081)
pnpm frontend:build
pnpm backend:sutExpect the Vue production build under frontend/dist. The CLI install URL is served from GCS in prod; locally, pnpm cli:bundle produces cli/dist/donut-cli.bundle.mjs, and the local LB (scripts/local-lb.mjs via pnpm cy:run / pnpm test) serves /doughnut-cli-latest/doughnut from that file — not Spring on 9081.
- GCP production notes — ordinary main pushes run CI only. Application Release starts on increasing immutable
vMAJOR.MINOR.PATCHtags after exact-commit CI succeeds and artifacts are available. Overlapping tags select the highest pending numeric version. After premature tagging, explicitly rerun the release once CI succeeds. Retry a recoverable release with the same immutable tag; when its identity must change or historical artifacts are unrecoverable, test the correction or revert on main and release the next patch as a forward correction. See the release runbook.
- pnpm: To clean up packages installed by pnpm, you can run pnpm store prune to remove unused packages from the store. To remove all packages for a specific project, navigate to the project directory and run pnpm recursive uninstall to uninstall all dependencies in the project and its subdirectories.
- direnv: To stop direnv from automatically loading the environment, you can simply delete the .envrc/ file in the project directory or run direnv deny in the project directory. To uninstall direnv, use the package manager you installed it with (e.g., brew uninstall direnv for macOS).
- Nix: If you want to remove the Nix package manager and all packages installed through it, you can run sudo rm -rf /nix to delete the Nix store. To uninstall Nix completely, follow the official Nix documentation for uninstallation instructions.
- We welcome product ideas and code contribution.
- Collaborate over:
- GitHub Discussions for product ideas/features,
- GitHub Issues for reporting issues or bugs, OR
- Odd-e-doughnut gitter
- FOSS style; Fork and submit GitHub PR.
- Please keep the PR small and on only one topic
- The code need to come with tests.