# Zinc documentation

Zinc is a native, Zotero-compatible reference manager for Windows, Linux and macOS. It opens a Zotero library, reads PDFs, adds items from the web, and cites into Word.

These pages are plain Markdown. Browse `docs/` on GitHub, or run the documentation site locally (see [Viewing these docs](#viewing-these-docs)).

## Where to start

| You want to | Read |
| --- | --- |
| Install the app | [Install](https://aborakati.github.io/zinc/user-guide/install.md), then [First run](https://aborakati.github.io/zinc/user-guide/first-run.md) |
| Learn the library | [Library basics](https://aborakati.github.io/zinc/user-guide/library.md), [Adding items](https://aborakati.github.io/zinc/user-guide/adding-items.md) |
| Read and annotate PDFs | [The PDF reader](https://aborakati.github.io/zinc/user-guide/reader.md) |
| Cite in Word or export references | [Citations](https://aborakati.github.io/zinc/user-guide/citations.md), [Word add-in](https://aborakati.github.io/zinc/user-guide/word.md), [Better BibTeX](https://aborakati.github.io/zinc/user-guide/better-bibtex.md) |
| Sync with Zotero | [Sync](https://aborakati.github.io/zinc/user-guide/sync.md) |
| Let an AI agent use your library | [MCP for AI agents](https://aborakati.github.io/zinc/user-guide/mcp.md) |
| Fix a problem | [Troubleshooting and FAQ](https://aborakati.github.io/zinc/user-guide/troubleshooting.md) |
| Build or change the app | [Developer guide](https://aborakati.github.io/zinc/developer-guide.md) |

## Contents

- [User guide](https://aborakati.github.io/zinc/user-guide.md)
- [Developer guide](https://aborakati.github.io/zinc/developer-guide.md)

## Viewing these docs

- On the website: <https://aborakati.github.io/zinc/>. It shows these pages with search and dark mode.
- On GitHub: open the `docs/` folder. Links are relative and Mermaid diagrams render in place.
- Locally, with search and dark mode: from the repository root run `bun run docs:dev` (live reload) or `bun run docs:preview` (a production build), then open the address it prints. The site lives in `website/` and reads `docs/` directly, so there is one copy of every page. Only Bun is needed.
- To check for broken links without serving: `bun run docs:build`. The build fails on a relative link to a page that does not exist.

## Writing docs

- A page is a Markdown file under `docs/`. Its first line is `# Title`; the title becomes the page title, so no front matter is needed.
- Link to other pages with relative links such as `[Sync](https://aborakati.github.io/zinc/sync.md#files)`. Do not link outside `docs/`.
- Put screenshots in `docs/screenshots/` and embed them with a relative path, for example `![Library](../screenshots/library-cards-light.png)`.
- Diagrams are Mermaid fences.
- A new page also needs an entry in the sidebar list in `website/astro.config.mjs`.
- The site's home, Features, Compare and Download pages (`website/src/pages/`) read their benchmark tables, feature lists and comparison grid from the repository README at build time (`website/src/lib/readme.ts`). Edit the README, not the pages, to change those; keep its headings, since the pages look them up by name.
