Add user guide, self-hosting, API, and contributing docs
docs/user-guide.md — magic-link sign-in, note basics, wikilink syntax, keyboard shortcuts, offline behaviour, and privacy notes (sessionStorage for tokens, tenant-scoped localStorage). docs/self-hosting.md — system requirements, Docker Compose quick-start, the full LIBRENOTES_* env-var matrix (which are required, which conditional), reverse proxy snippets for Caddy and nginx, volume layout, the in-binary healthcheck, and update/rollback procedure. docs/api.md — every public endpoint: auth (login/verify), notes CRUD, /api/whoami, /healthz. Status codes per endpoint, the optimistic-locking ?base=<unix> contract for PUT/DELETE, note-ID regex, and the rate-limit policy. CONTRIBUTING.md — dev setup (Nix flake .#dev, plain Go, Docker), package layout overview, coding standards (one-way dep flow, tenant FS gateway requirement), branch naming, commit format, and the PR process. Also points security reports at security@librete.ch rather than public issues. Closes #29. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,83 @@
|
||||
# User guide
|
||||
|
||||
Welcome to librenotes — an open-source, multi-tenant notes app
|
||||
with bi-directional links and Markdown.
|
||||
|
||||
## Getting started
|
||||
|
||||
1. Visit [https://librenot.es](https://librenot.es).
|
||||
2. Click **Sign in with email** and enter your address.
|
||||
3. Check your inbox; the magic link is valid for 15 minutes and
|
||||
can be used once.
|
||||
4. Clicking the link signs you in and drops you into the app.
|
||||
|
||||
There is no password to remember. Each link is a one-time
|
||||
credential; the session it creates lasts 24 hours.
|
||||
|
||||
## Notes are Markdown files
|
||||
|
||||
Each note is a single Markdown (`.md`) file scoped to your
|
||||
tenant directory on the server. The first H1 line is the title;
|
||||
the rest is content. You can edit notes in the web UI today; in
|
||||
a self-hosted setup you can also drop files directly into the
|
||||
data directory and they will appear in your notebook on next
|
||||
sync.
|
||||
|
||||
```markdown
|
||||
# Project ideas
|
||||
|
||||
A few directions worth chasing this quarter.
|
||||
|
||||
- Try [[graph-view]] for the dashboard
|
||||
- Read [[zettelkasten-overview]]
|
||||
```
|
||||
|
||||
### Bi-directional links (wikilinks)
|
||||
|
||||
Use `[[note-id]]` to link to another note. The target's backlinks
|
||||
list will include the source automatically. If the target does
|
||||
not exist yet, the link will create it on click. Note IDs are
|
||||
short slugs: lowercase letters, digits, hyphens, underscores. A
|
||||
note titled "Project Ideas" might have the ID `project-ideas`.
|
||||
|
||||
### Markdown syntax
|
||||
|
||||
Standard CommonMark is supported: headings, lists, links, code
|
||||
blocks, fenced code with language hints, blockquotes, tables,
|
||||
images. Inline HTML is sanitised on render.
|
||||
|
||||
## Keyboard shortcuts
|
||||
|
||||
| Action | Shortcut |
|
||||
| ------ | -------- |
|
||||
| New note | `Ctrl+N` / `Cmd+N` |
|
||||
| Save current note | `Ctrl+S` / `Cmd+S` |
|
||||
| Open note finder | `Ctrl+P` / `Cmd+P` |
|
||||
| Toggle preview | `Ctrl+\\` / `Cmd+\\` |
|
||||
| Toggle theme | `Ctrl+Shift+T` |
|
||||
| Sign out | (header menu) |
|
||||
|
||||
## Offline use
|
||||
|
||||
librenotes works offline. The Progressive Web App caches the
|
||||
shell so you can open the page without a network, and your notes
|
||||
are mirrored into IndexedDB so they are readable and editable
|
||||
offline. Edits made offline are queued and pushed when you come
|
||||
back online; conflicts (when both you and another session edited
|
||||
the same note) prompt you to keep one version or the other.
|
||||
|
||||
## Privacy
|
||||
|
||||
Your notes are stored on disk per-tenant, isolated by the
|
||||
filesystem sandbox; no other user can access your directory. The
|
||||
session token is held in `sessionStorage` so closing the browser
|
||||
tab signs you out on shared devices. Per-user UI preferences live
|
||||
in `localStorage` under a tenant-scoped prefix and are wiped on
|
||||
logout.
|
||||
|
||||
For the full privacy policy see [/privacy.html](/privacy.html).
|
||||
|
||||
## Self-hosting
|
||||
|
||||
Want to run your own instance instead? See
|
||||
[self-hosting.md](./self-hosting.md).
|
||||
Reference in New Issue
Block a user