diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e823e2e..31c68802 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,17 +77,19 @@ cd frontend && npm install && cd .. On macOS, PDF export through WeasyPrint also requires Homebrew native libraries: ```bash -brew install glib pango cairo libffi +brew install glib pango cairo gdk-pixbuf libffi ``` The development helper adds `/opt/homebrew/lib` to -`DYLD_FALLBACK_LIBRARY_PATH` automatically so WeasyPrint can locate -`libgobject-2.0` and related libraries. If those libraries are missing, PDF -export falls back to PyMuPDF with simpler layout. +`DYLD_FALLBACK_LIBRARY_PATH` automatically on Apple Silicon Homebrew installs +so WeasyPrint can locate `libgobject-2.0` and related libraries. For Intel +Homebrew installs or manual backend launches, follow the platform-specific +[macOS setup guide](./docs/PrepareForMacUser.md). If WeasyPrint is unavailable, +PDF export falls back to PyMuPDF with simpler layout. Fuller macOS setup notes are in [docs/PrepareForMacUser.md](./docs/PrepareForMacUser.md). -On Windows, WeasyPrint requires native system libraries (Cairo, Pango) that are not available by default. See [docs/PrepareForWindowsUser.md](./docs/PrepareForWindowsUser.md) for the MSYS2 setup steps. +On Windows, WeasyPrint requires native system libraries that are not available by default. See [docs/PrepareForWindowsUser.md](./docs/PrepareForWindowsUser.md) for MSYS2 UCRT64 installation and the `WEASYPRINT_DLL_DIRECTORIES` setting. 4. Configure the frontend environment file: @@ -111,6 +113,8 @@ Use the project helper for normal desktop development: ./scripts/dev-tauri.sh ``` +On Windows, use `.\scripts\dev-tauri.ps1` from PowerShell. The wrapper invokes Git Bash at `C:\Program Files\Git\bin\bash.exe`; install Git for Windows at that location or run the shell script directly from Git Bash. + This starts the FastAPI backend and launches the Tauri desktop shell. The backend URL is printed by the script. When it uses the default port, the API docs are available at: diff --git a/README.MD b/README.MD index 2f0d1a41..597e77d6 100644 --- a/README.MD +++ b/README.MD @@ -1,137 +1,103 @@

Markdown Reader

-

The open-source, local-first Markdown editor with native AI capabilities.

- +

A local-first Markdown editor with live preview and AI-assisted writing tools.

+ [![macOS Apple Silicon](https://img.shields.io/badge/macOS-Apple_Silicon-black?logo=apple)](#desktop-downloads) [![Windows x64](https://img.shields.io/badge/Windows-x64-blue?logo=windows)](#desktop-downloads) [![Linux x64](https://img.shields.io/badge/Linux-x64-yellow?logo=linux)](#desktop-downloads) - -
- Image + + Markdown Reader application screenshot
---- +Markdown Reader is a desktop Markdown editor and reader built with a Next.js frontend, a local FastAPI backend, and Tauri. It combines tabbed editing, live preview, a rich-text Focus Mode, optional AI assistance, project-wide tools, document conversion, citations, and publication export. -## Table of Contents +Files are managed locally by the app. Document or note content is sent to an external AI provider only when you use an AI feature that includes that content in its request. See the [AI panel and Notes Context guide](./docs/ProjectAIWorkflows.md) for details. -- [Why Markdown Reader?](#-why-markdown-reader) - - [Key Features](#key-features) -- [Quick Start](#-quick-start) -- [Desktop Downloads](#-desktop-downloads) -- [Slash Commands](#-slash-commands) -- [Local Model Support](#-local-model-support) -- [Universal File Import](#-universal-file-import) -- [Academic Citations](#-academic-citations) -- [Architecture](#-architecture) -- [Technical Documentation](#-technical-documentation) -- [Contributing](#-contributing) +## Features ---- +- **Editing and preview:** Edit Markdown in tabs with a rendered preview, document statistics, adjustable editor font size, and split-view controls. +- **Focus Mode:** Switch to a distraction-reduced rich Markdown editor with CommonMark/GFM support, math, paste handling, and an editor slash-command menu. +- **AI-assisted writing:** Chat about the active document, translate full documents or selections, use sentence-pair translation, summarize, format text, generate a table of contents, and clean up code blocks. +- **Reviewable AI changes:** Inspect chat suggestions before applying them; project-level changes are presented as diffs for review before they are staged in editor tabs. +- **Project workflows:** Translate Markdown files into a separate output tree, retry failed files, prepare multi-file AI changes, and assemble selected open documents into a publication draft. +- **Notes Context:** Index a local Markdown/text notes folder and retrieve relevant excerpts for AI chat using a local SQLite index. +- **AI providers:** Configure OpenAI, Anthropic, OpenRouter, or OpenAI-compatible endpoints, including local servers such as Ollama and LM Studio. +- **File conversion:** Open Markdown and text directly; convert supported HTML, PDF, DOCX, Office, spreadsheet, EPUB, XML, archive, image, audio, email, and notebook files when the relevant converter dependencies are available. +- **Citations and publication:** Browse a BibTeX library, insert citation-key markers into Markdown, combine selected open documents in a chosen order, and export supported formats. +- **Desktop integration:** Use native file and folder dialogs and packaged desktop releases through Tauri. -## ๐ŸŒŸ Why Markdown Reader? +Feature availability can depend on the selected provider, installed optional dependencies, and whether the app is running as a packaged desktop app or in development. Review AI-generated changes, translations, and converted documents before relying on them. -Most modern writing apps force you to choose between **privacy** and **power**. Cloud-based AI editors train on your data, while local editors often lack intelligent features. +## Desktop downloads -**Markdown Reader bridges the gap.** It is a native desktop application built on Tauri, ensuring your files stay locally on your machine. But it also seamlessly integrates with **OpenAI, Anthropic, OpenRouter, and Local LLMs**, bringing powerful AI-assisted writing directly to your offline workflow. +Official release builds and platform-specific installation notes are available from the [Markdown Reader downloads page](https://petertzy.github.io/markdown-reader/). -### Key Features +| Platform | Available release | +| --- | --- | +| macOS | Apple Silicon (aarch64-apple-darwin) | +| Windows | x64 (x86_64-pc-windows-msvc) | +| Linux | x64 (x86_64-unknown-linux-gnu) | -- ๐Ÿ”’ **Local-First Architecture**: Your files never leave your machine unless you explicitly call an external AI API. -- ๐Ÿค– **Bring-Your-Own-AI**: Configure OpenAI, Anthropic, OpenRouter, OpenAI-compatible providers, or local models. -- โœ๏ธ **Intelligent Editing**: AI-assisted translation, sentence-by-sentence comparison, summarization, formatting, and code-block cleanup. -- โšก **Slash Commands**: Type `/` in the editor to trigger AI actions or insert a table inline, without opening the AI panel. -- ๐Ÿ›ก๏ธ **Audit & Rollback**: Review all AI suggestions before applying them. Reject or rollback changes with a single click. -- ๐Ÿ–ฅ๏ธ **Native Desktop Feel**: Built with Next.js and packaged with Tauri for blazing-fast performance. -- ๐Ÿ“Š **Document Statistics**: View word count, character count, heading count, and estimated reading time for the current document (based on 238 words per minute). +macOS Intel is not currently included in the release matrix. See [Code signing and distribution](./docs/CodeSigningAndDistribution.md) for release and signing details. ---- +## Run from source -## ๐Ÿš€ Quick Start +### Prerequisites -Get the app running locally for development in under a minute: +- Python 3.11 to 3.13 +- [uv](https://docs.astral.sh/uv/) +- Node.js 20.9.0 or newer and npm +- Rust and the Tauri prerequisites for desktop-shell development + +Python 3.14 is not currently supported because some optional MarkItDown dependencies do not yet provide compatible wheels. + +### macOS and Linux ```bash -# Prerequisites: Python 3.11-3.13, Node.js 20.9.0+, and uv git clone https://github.com/petertzy/markdown-reader.git cd markdown-reader - -# Install dependencies -uv sync -cd frontend && npm install && cd .. - -# Configure frontend environment variables cp frontend/.env.local.example frontend/.env.local - -# Launch the Tauri desktop app ./scripts/dev-tauri.sh ``` -The development helper starts the FastAPI backend on `127.0.0.1:8000` when that -port is available. If port `8000` is already occupied by another process, it -automatically chooses a free local port and passes it to the Tauri shell. To -request a specific backend port, run: +The helper installs/synchronizes the Python and frontend dependencies, starts the local FastAPI backend, and launches the Tauri development shell. It uses port 8000 when available and tries nearby ports if necessary. To request a port explicitly: ```bash MARKDOWN_READER_BACKEND_PORT=8010 ./scripts/dev-tauri.sh ``` -> PDF export may need extra system libraries on macOS and Windows. See -> [Technical Documentation](./docs/TECHNICAL.md#pdf-export-dependencies) for -> those steps. +### Windows ---- - -## ๐Ÿ“ฆ Desktop Downloads +From PowerShell, create the frontend environment file and launch the Windows helper: -We provide official desktop release builds through GitHub Actions. +```powershell +git clone https://github.com/petertzy/markdown-reader.git +cd markdown-reader +Copy-Item frontend/.env.local.example frontend/.env.local +.\scripts\dev-tauri.ps1 +``` -| OS | Architecture | Download | -| ----------- | ------------- | ----------------------------------------------------------------- | -| **macOS** | Apple Silicon | [Download .dmg](https://petertzy.github.io/markdown-reader/) | -| **Windows** | x64 | [Download .exe](https://petertzy.github.io/markdown-reader/) | -| **Linux** | x64 | [Download .AppImage](https://petertzy.github.io/markdown-reader/) | +The PowerShell and batch wrappers call Git Bash at `C:\Program Files\Git\bin\bash.exe`. Install Git for Windows at that location, or run `scripts/dev-tauri.sh` from Git Bash. -_(Note: macOS Intel builds are currently unsupported due to advanced PDF dependency constraints)._ +When the backend uses port 8000, its API documentation is available at http://127.0.0.1:8000/docs. If another port is selected, use the port printed by the helper. ---- +PDF export may require native system libraries for WeasyPrint. See the [technical documentation](./docs/TECHNICAL.md#pdf-export-dependencies), [macOS setup](./docs/PrepareForMacUser.md), and [Windows setup](./docs/PrepareForWindowsUser.md). -## โšก Slash Commands +## Slash commands -Type `/` at the start of a line (or after whitespace) in the editor to open an inline command menu: +Type `/` at the start of a line or after whitespace in the main editor to open the command menu. -| Command | Behavior | +| Command | Action | | --- | --- | -| `/summarize` | Summarizes the document via AI | -| `/translate` | Opens the AI panel's Translate tab | -| `/format` | Applies Markdown formatting via AI | -| `/toc` | Generates a table of contents via AI | -| `/fix-code` | Fixes code block fences via AI | -| `/insert-table` | Inserts a Markdown table (no AI call) | -| `/insert-toc` | Inserts a table of contents generated locally from the document headings (no AI call) | +| `/summarize` | Summarize the document with AI | +| `/translate` | Open the AI panel's Translate tab | +| `/format` | Format text with AI | +| `/toc` | Generate a table of contents with AI | +| `/fix-code` | Clean up Markdown code fences with AI | +| `/insert-table` | Insert a table without an AI request | +| `/insert-toc` | Generate a table of contents locally from document headings | -Use the arrow keys to navigate, Enter to run a command, or Escape to dismiss the menu. - ---- - -## ๐Ÿง  Local Model Support - -Markdown Reader can call locally hosted OpenAI-compatible model servers. In the AI settings panel, choose **Local Model**, select **LM Studio**, **Ollama**, or **Custom**, fetch available models, and save the model you want to use. Local endpoints do not require an API key unless your local server is configured to require one. - ---- - -## ๐Ÿ“ฅ Universal File Import - -Markdown Reader can import Markdown/text files directly and convert HTML, PDF, DOCX, Office files, CSV, EPUB, XML, archives, images, audio, Outlook messages, and Jupyter notebooks to Markdown through the bundled MarkItDown converter. Python 3.14 is not currently supported because some MarkItDown optional dependencies do not publish Python 3.14 wheels yet. - ---- - -## ๐Ÿ“š Academic Citations - -Use the **Cite** panel to load a BibTeX `.bib` library, search by citation key, author, title, year, publication venue, or entry type, and insert citation references such as `[@doe2024]` at the current cursor position. In the desktop app, click **Select** to choose a `.bib` file with the native file picker. In browser development mode, the same button uploads the selected `.bib` file to the local backend and stores it as the active citation library. - -Markdown Reader preserves citation syntax during editing and export, including HTML, DOCX, and PDF output. - ---- +Use the arrow keys to move through the menu, Enter to run a command, and Escape to dismiss it. Focus Mode has its own editor slash-command menu. ## ๐Ÿ—๏ธ Architecture @@ -184,36 +150,22 @@ The explorer supports zooming, panning, node inspection, and exporting a selecte --- -## ๐Ÿ“– Technical Documentation +## Documentation -For advanced and implementation details, see [Technical Documentation](./docs/TECHNICAL.md). It covers: +- [User guide](./docs/UserGuide.md): editor modes, files and projects, AI settings, import, citations, and export. +- [AI panel and Notes Context](./docs/ProjectAIWorkflows.md): Chat, document Work, provider settings, and local notes retrieval. +- [Project workflows](./docs/ProjectWorkflows.md): project translation, reviewable project-wide AI changes, and publication drafts. +- [Keyboard shortcuts](./docs/KeyboardShortcuts.md): default application and editor shortcuts. +- [Documentation index](./docs/index.md): user guides, technical references, platform notes, and planning documents. +- [Technical documentation](./docs/TECHNICAL.md): architecture, local backend security, PDF export dependencies, and local packaging. +- [Code signing and distribution](./docs/CodeSigningAndDistribution.md): current release signing notes and distribution research. +- [macOS setup](./docs/PrepareForMacUser.md) and [Windows setup](./docs/PrepareForWindowsUser.md): platform-specific PDF export dependencies. +- [Contributing guide](./CONTRIBUTING.md): development setup, checks, and contribution workflow. -- Architecture, including the FastAPI backend, Next.js/Tauri frontend, and the bundled Python sidecar -- Local backend security and the Desktop Content Security Policy -- PDF export dependencies for macOS and Windows -- Building release artifacts locally +## Contributing -In short: Markdown Reader is split into a FastAPI backend and a Next.js frontend packaged with Tauri. When packaged for desktop use, the Python backend is bundled as a silent Tauri sidecar process, dynamically assigning ports at runtime to avoid conflicts. +Contributions are welcome, including bug fixes, focused improvements, tests, and documentation updates. Start with the [contributing guide](./CONTRIBUTING.md), keep changes focused, and run the checks relevant to the files you changed. ---- +## License -## ๐Ÿค Contributing - -Contributions are highly welcome! Whether you're fixing a bug, suggesting a feature, or helping us write documentation, we'd love to have you. - -To get started: - -1. `git checkout -b your-feature-branch` -2. Run linting: `uv run ruff check .` -3. Run tests: `uv run python -m unittest discover -s tests` -4. Open a Pull Request! - -After cloning, run `uv sync --extra dev` and `uv run pre-commit install` to set up linting hooks. - -See our full [Contribution Guidelines](CONTRIBUTING.md) for more details. - ---- - -
- Released under the MIT License. See LICENSE.md for details. -
+Released under the [MIT License](./LICENSE.md). diff --git a/docs/CodeSigningAndDistribution.md b/docs/CodeSigningAndDistribution.md index 3267c241..3be42fbf 100644 --- a/docs/CodeSigningAndDistribution.md +++ b/docs/CodeSigningAndDistribution.md @@ -2,7 +2,7 @@ > Addresses: [Issue #326](https://github.com/petertzy/markdown-reader/issues/326) -Packaged desktop apps that are unsigned trigger operating-system trust warnings โ€” +Packaged desktop apps without an appropriate platform signature can trigger operating-system trust warnings โ€” macOS Gatekeeper ("unidentified developer" / "damaged") and Windows Defender SmartScreen. For non-technical users these warnings often mean abandoning the install. This document surveys the practical options, costs, and free/open-source @@ -20,9 +20,21 @@ routes, with an emphasis on what works well in an automated GitHub Actions relea Gatekeeper warning; the user still has to allow it once in **System Settings โ†’ Privacy & Security**. -**Recommendation:** adopt **SignPath Foundation** (free for open source) for Windows, -ship **ad-hoc signed** macOS with clear first-run instructions (or pay the $99 for a -frictionless experience), and publish **checksums + a GPG-signed** Linux release. +**Research recommendation (not current release configuration):** consider a Windows signing provider, use the optional macOS signing/notarization path when the required credentials are provisioned, and add a GPG signature for the existing Linux checksum files. + +## Current repository release status + +The statements below were checked against `.github/workflows/release.yml` and `frontend/src-tauri/tauri.conf.json` on **2026-11-04**. They describe repository configuration, not whether a particular release run has valid secrets or completed notarization. + +| Area | Current configuration | +| --- | --- | +| Release build matrix | macOS Apple Silicon, Windows x64, and Linux x86_64 | +| macOS | The workflow contains a conditional Apple certificate import and Developer ID identity-resolution step. It runs only when `APPLE_CERTIFICATE` is configured. Apple notarization credentials are passed to the Tauri release action when configured. Verify an individual release run and artifact before calling a build Developer ID signed or notarized. | +| Windows | No Windows signing command or Azure Artifact Signing step is currently configured in the release workflow. | +| Linux | The workflow builds Linux x86_64 bundles and generates/uploads a per-target SHA-256 checksum file. No GPG-signed manifest is currently generated. | +| Tauri bundle settings | The Tauri config includes macOS entitlements. A Windows `bundle.windows.signCommand` is not configured. | + +The release workflow and its secrets can change independently of this research document. Check the current workflow and the specific release run before describing an artifact as signed, notarized, or verified. ## macOS @@ -34,12 +46,7 @@ macOS is the one platform where a paid membership is effectively required for a bundle for **notarization**. - The **free** Apple Developer plan can only be used for local testing/development and **cannot notarize**. -- **Ad-hoc signing** is *required* for apps to launch at all on Apple Silicon when - downloaded from the internet, but it does **not** clear the Gatekeeper prompt. - Tauri already ad-hoc signs by default when no `bundle.macOS.signingIdentity` is - set, and this repo's `tauri.conf.json` has no `macOS` block at all โ€” so current - builds are already ad-hoc signed. Setting `"signingIdentity": "-"` explicitly - documents the intent but changes nothing functionally. +- **Ad-hoc signing** is commonly used when no Developer ID signing identity is supplied. It does not remove Gatekeeper warnings. The repository's Tauri configuration includes a macOS entitlements file but does not pin a Developer ID identity. The release workflow has an optional certificate-import and identity-resolution path; see the current repository status below. - There is no reputable free notarization path. ## Windows @@ -84,11 +91,8 @@ reputation still has to accrue over time. No platform-wide certificate requirement; trust depends on the distribution method. -- Currently `"targets": "all"` in `tauri.conf.json` produces **deb**, **rpm**, and - **AppImage** on Linux. The repo also ships an AUR `PKGBUILD`. There is no Flatpak - or Snap manifest today; adding one would be new work. -- Publish **SHA-256 checksums** and a **GPG-signed** release manifest. The release - workflow currently does neither. +- The Tauri configuration targets all supported bundle formats. The release workflow currently builds Linux x86_64 artifacts. The repository also ships an AUR `PKGBUILD`; it does not currently include Flatpak or Snap manifests. +- The release workflow generates and uploads a per-target **SHA-256 checksum file**. It does not currently create a GPG-signed release manifest. - This is free and is the community-standard baseline. ## Free / open-source options @@ -111,14 +115,10 @@ Other zero-cost routes: ## Recommended next steps -1. **Windows:** apply to **[SignPath Foundation](https://signpath.org/)** (free, - OSS-eligible, application-based) and wire it into the release workflow. -2. **macOS:** decide between paying **$99/year** for a clean, notarized install, or - shipping **ad-hoc signed** with clear first-run guidance - (see `docs/PrepareForMacUser.md`). -3. **Linux:** add **SHA-256 checksums + a GPG-signed** manifest to the release. -4. Add an **opt-in signing step** to `.github/workflows/release.yml` (currently it - builds all three platforms with **no signing configured**). +1. **Windows:** evaluate a signing provider such as [SignPath Foundation](https://signpath.org/) and implement it only after eligibility, secrets, and CI configuration are confirmed. +2. **macOS:** keep the optional certificate/notarization path aligned with the secrets configured for the release workflow, and verify the output of each release run. +3. **Linux:** consider adding a GPG signature for the existing SHA-256 checksum artifacts. +4. Re-check this document whenever `.github/workflows/release.yml` or `frontend/src-tauri/tauri.conf.json` changes. ### Budget options compared @@ -137,16 +137,10 @@ Other zero-cost routes: > the [Artifact Signing FAQ](https://learn.microsoft.com/azure/artifact-signing/faq); > certificate and SmartScreen comparisons come from > [Code signing options for Windows app developers](https://learn.microsoft.com/windows/apps/package-and-deploy/code-signing-options). -> All figures are USD and were verified on **2026-10-03** โ€” re-check before quoting +> All figures are USD and were checked on **2026-10-03** โ€” re-check before quoting > them in a funding request, since vendor pricing changes without notice. -> **Publishing note:** this file is registered in `mkdocs.yml`, but **no workflow -> currently builds or deploys the docs site** โ€” `mkdocs` appears only in the optional -> `docs` dependency group in `pyproject.toml`. Until a docs-deploy workflow exists, -> this document is only reachable from the repository itself. See also -> `docs/HostingStrategy.md` for the download-channel plan, and the user-facing -> install note in `distribution/index.html`, which already tells macOS users how to -> work around the Gatekeeper prompt while builds remain unnotarized. +**Documentation publishing note:** the current GitHub Pages workflow deploys the `distribution/` directory, not an MkDocs documentation site. This Markdown reference remains available in the repository; do not infer that a separate documentation website is being built or deployed. ## Appendix: Tauri signing environment variables @@ -251,15 +245,9 @@ Example opt-in macOS step (only runs when the secret is present): APPLE_SIGNING_IDENTITY: ${{ steps.cert.outputs.cert_id }} ``` -> `APPLE_SIGNING_IDENTITY` must be the certificate's SHA-1 fingerprint, not a -> friendly name. The "Resolve signing identity" step reads it out of the keychain and -> exports it as a step output โ€” without that step the identity resolves to an empty -> string and the build fails at signing time. `KEYCHAIN_PASSWORD` must also be -> provided as a secret; it is used to create and unlock the temporary keychain. +> The repository's release workflow resolves the installed **Developer ID Application** identity from the temporary keychain and passes that value to the Tauri release action. Keep the identity-resolution step and the Tauri action's expected identity format aligned when changing this workflow. `KEYCHAIN_PASSWORD` is used to create and unlock the temporary keychain. > > Notarization additionally requires `APPLE_API_ISSUER` / `APPLE_API_KEY` / > `APPLE_API_KEY_PATH` (or the Apple ID trio) to be passed to `tauri-action`. -> Note: this appendix documents the wiring only. Enabling it requires repository -> secrets and (for macOS) a paid Apple Developer account; the release workflow is -> intentionally left unsigned until those are provisioned. +> The Windows Azure Artifact Signing configuration above is an implementation option, not a currently configured signing step. The current release workflow does not define a Windows `bundle.windows.signCommand`. The optional macOS certificate import and identity-resolution steps are present; the signing/notarization outcome depends on the required repository secrets and Apple credentials. diff --git a/docs/HostingStrategy.md b/docs/HostingStrategy.md index 3c96bf56..b10fafb1 100644 --- a/docs/HostingStrategy.md +++ b/docs/HostingStrategy.md @@ -1,8 +1,10 @@ ## Hosting & Distribution Strategy +> **Current implementation status (2026-11-04):** this file records an earlier proposal to use Cloudflare Pages. The repository currently deploys the `distribution/` directory to **GitHub Pages** through [`.github/workflows/deploy-distribution.yml`](https://github.com/petertzy/markdown-reader/blob/main/.github/workflows/deploy-distribution.yml). That workflow is triggered by relevant changes on `main` or manually. The Cloudflare steps below are historical planning notes, not instructions for the currently deployed site. Provider limits, pricing, and product details in the proposal are time-sensitive and should be re-checked before making a hosting decision. + > Addresses: [Issue #186](https://github.com/petertzy/markdown-reader/issues/186) ยท [Issue #189](https://github.com/petertzy/markdown-reader/issues/189) -### Recommended Stack +### Historical proposal: GitHub Releases + Cloudflare Pages **GitHub Releases + Cloudflare Pages** โ€” fully free, production-grade, zero maintenance overhead. diff --git a/docs/KeyboardShortcuts.md b/docs/KeyboardShortcuts.md new file mode 100644 index 00000000..faf4eedc --- /dev/null +++ b/docs/KeyboardShortcuts.md @@ -0,0 +1,56 @@ +# Keyboard Shortcuts + +This page lists the default shortcuts defined by the application. The primary modifier is **Command** on macOS and **Ctrl** on Windows and Linux. The application does not currently expose a shortcut-customization interface. + +## Files and tabs + +| Action | macOS | Windows/Linux | +| --- | --- | --- | +| New file | Command+N | Ctrl+N | +| Open file | Command+O | Ctrl+O | +| Save file | Command+S | Ctrl+S | +| Close current tab | Command+W | Ctrl+W | +| Close all tabs | Command+Shift+W | Ctrl+Shift+W | + +## Editing and formatting + +| Action | macOS | Windows/Linux | +| --- | --- | --- | +| Undo | Command+Z | Ctrl+Z | +| Redo | Command+Shift+Z | Ctrl+Y or Ctrl+Shift+Z | +| Search | Command+F | Ctrl+F | +| Replace | Command+Option+F | Ctrl+H | +| Bold | Command+B | Ctrl+B | +| Italic | Command+I | Ctrl+I | +| Underline | Command+U | Ctrl+U | +| Heading 1 | Command+1 | Ctrl+1 | +| Heading 2 | Command+2 | Ctrl+2 | +| Heading 3 | Command+3 | Ctrl+3 | +| Normal text | Command+0 | Ctrl+0 | +| Insert table | Command+Option+T | Ctrl+Alt+T | + +## Export and view + +| Action | macOS | Windows/Linux | +| --- | --- | --- | +| Export to HTML | Command+Option+H | Ctrl+Alt+H | +| Export to Word (DOCX) | Command+Option+D | Ctrl+Alt+D | +| Export to PDF | Command+Option+P | Ctrl+Alt+P | +| Toggle dark mode | F6 | F6 | +| Toggle AI panel | Command+Shift+A | Ctrl+Shift+A | +| Open preview in browser | Command+Option+B | Ctrl+Alt+B | +| Full-width editor | Command+Option+Left Arrow | Ctrl+Alt+Left Arrow | +| Balanced split view | Command+Option+Down Arrow | Ctrl+Alt+Down Arrow | +| Full-width preview | Command+Option+Right Arrow | Ctrl+Alt+Right Arrow | + +The search, replace, formatting, and table shortcuts are tied to the main Monaco editor. Focus Mode uses a different rich editor and has its own slash-command menu; use the toolbar and Focus Mode's editor controls for actions that are not handled by Monaco. File-level and view-level shortcuts are application commands. + +Shortcut execution respects editor focus. For example, an editor-scoped shortcut should not intercept native undo or typing while focus is in an ordinary text input such as the AI prompt field. + +The main editor slash menu is separate from keyboard shortcuts: type `/` at the start of a line or after whitespace, use the arrow keys to select a command, Enter to execute it, and Escape to dismiss it. Focus Mode has its own slash-command menu. + +## Related documentation + +- [User guide](./UserGuide.md) +- [AI panel and Notes Context](./ProjectAIWorkflows.md) +- [Project workflows](./ProjectWorkflows.md) diff --git a/docs/PrepareForMacUser.md b/docs/PrepareForMacUser.md index 00e617be..6007bb63 100644 --- a/docs/PrepareForMacUser.md +++ b/docs/PrepareForMacUser.md @@ -1,47 +1,46 @@ +# macOS PDF Export Dependencies -For Mac users, you should first run the following additional command: -```bash -brew install cairo pango gdk-pixbuf libffi -``` -Then reactivate your virtual environment: -```bash -deactivate -source .venv/bin/activate -``` -#### If you are using Apple Silicon (M1/M2/M3/M4) +Markdown Reader uses WeasyPrint for PDF export when the required native libraries can be loaded. The development helper adds `/opt/homebrew/lib` to `DYLD_FALLBACK_LIBRARY_PATH` automatically when that directory exists. A manual setup is useful when running Python or the backend outside the helper. -Run: -```bash -export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib -``` -Then test: -```bash -python -c "from weasyprint import HTML; print('OK')" -``` -#### If you are using an Intel Mac +## 1. Install Homebrew libraries -Run: -```bash -export DYLD_FALLBACK_LIBRARY_PATH=/usr/local/lib -``` -#### Make It Permanent (Recommended) +Install Homebrew if it is not already available, then run: -If the previous step works, add the environment variable to your shell configuration. -If you are using **zsh**, open: ```bash -nano ~/.zshrc +brew install glib pango cairo gdk-pixbuf libffi ``` -Add the following line: -#### Apple Silicon +## 2. Make Homebrew libraries discoverable + +For Apple Silicon Macs using the standard Homebrew location: + ```bash -export DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib +export DYLD_FALLBACK_LIBRARY_PATH="/opt/homebrew/lib${DYLD_FALLBACK_LIBRARY_PATH:+:$DYLD_FALLBACK_LIBRARY_PATH}" ``` -#### Intel Mac + +For Intel Macs using the standard Homebrew location: + ```bash -export DYLD_FALLBACK_LIBRARY_PATH=/usr/local/lib +export DYLD_FALLBACK_LIBRARY_PATH="/usr/local/lib${DYLD_FALLBACK_LIBRARY_PATH:+:$DYLD_FALLBACK_LIBRARY_PATH}" ``` -Save the file, then run: + +If Homebrew is installed somewhere else, use the corresponding library directory. To make the setting persistent in zsh, add the appropriate export line to `~/.zshrc` and run `source ~/.zshrc`. + +## 3. Verify WeasyPrint + +After synchronizing the project Python environment with `uv sync`, run: + ```bash -source ~/.zshrc +uv run python -c "from weasyprint import HTML; print('WeasyPrint import OK')" ``` + +If the import succeeds but PDF export still falls back, inspect the reported WeasyPrint/system-library diagnostics and confirm that the shell launching the backend has the library path. + +## Notes + +For upstream installation and native-library troubleshooting details, see the [WeasyPrint first steps documentation](https://doc.courtbouillon.org/weasyprint/latest/first_steps.html). + +- The project development helper adds the Apple Silicon Homebrew library path when `/opt/homebrew/lib` exists; it does not automatically add the Intel `/usr/local/lib` path. +- WeasyPrint is preferred when available. The application can fall back to PyMuPDF for PDF export, with simpler layout fidelity. +- For Windows, follow [Prepare for Windows](./PrepareForWindowsUser.md). +- For architecture and export details, see [Technical Documentation](./TECHNICAL.md#pdf-export-dependencies). diff --git a/docs/PrepareForWindowsUser.md b/docs/PrepareForWindowsUser.md index 0ae1a2f7..99f6764c 100644 --- a/docs/PrepareForWindowsUser.md +++ b/docs/PrepareForWindowsUser.md @@ -1,45 +1,55 @@ -For Windows users, WeasyPrint requires native system libraries (Cairo, Pango) that are not available by default. The recommended way to install them is via **MSYS2**. +# Windows PDF Export Dependencies -#### 1. Install MSYS2 +Markdown Reader uses WeasyPrint for PDF export when its native libraries can be loaded. On Windows, install the runtime libraries through MSYS2 UCRT64 and point WeasyPrint at the UCRT64 DLL directory. -Download and install MSYS2 from [https://www.msys2.org/](https://www.msys2.org/), then follow the first-time setup instructions on the site. +## 1. Install MSYS2 -#### 2. Install the required libraries +Download and install [MSYS2](https://www.msys2.org/). Complete its first-time update steps, then open the **MSYS2 UCRT64** terminal from the Start menu. -Open the **MSYS2 UCRT64** terminal (search for "MSYS2 UCRT64" in the Start menu) and run: +## 2. Install Pango + +In the MSYS2 UCRT64 terminal, run: ```bash pacman -S mingw-w64-ucrt-x86_64-pango ``` -#### 3. Add MSYS2 to your Windows PATH +Accept the package installation prompts. This installs the Pango runtime and its required UCRT64 dependencies. -Add the MSYS2 UCRT64 `bin` directory to your Windows `PATH` environment variable: +## 3. Configure WeasyPrint DLL discovery -``` +WeasyPrint uses the `WEASYPRINT_DLL_DIRECTORIES` environment variable to locate the MSYS2 runtime DLLs. The default MSYS2 UCRT64 path is: + +```text C:\msys64\ucrt64\bin ``` -To do this permanently: -1. Open **System Properties** โ†’ **Advanced** โ†’ **Environment Variables** -2. Under **System variables**, select `Path` and click **Edit** -3. Click **New** and add `C:\msys64\ucrt64\bin` -4. Click **OK** to save +For the current PowerShell session, run: + +```powershell +$env:WEASYPRINT_DLL_DIRECTORIES = 'C:\msys64\ucrt64\bin' +``` + +To configure it persistently, open **System Properties โ†’ Advanced โ†’ Environment Variables**, add a user variable named `WEASYPRINT_DLL_DIRECTORIES`, and set its value to the UCRT64 `bin` directory. Open a new terminal after changing the variable. -#### 4. Reactivate your virtual environment +This is a WeasyPrint DLL-search setting; adding the directory to the general Windows `PATH` is not the documented replacement for this variable. -Open a new Command Prompt or PowerShell window (so the updated PATH takes effect), then reactivate your virtual environment: +## 4. Verify the runtime -```cmd -.\.venv\Scripts\activate +From the repository root, after installing the Python dependencies, run: + +```powershell +uv run python -m weasyprint --info +uv run python -c "from weasyprint import HTML; print('WeasyPrint import OK')" ``` -#### 5. Verify the installation +If the import fails, confirm the MSYS2 installation path and the value of `WEASYPRINT_DLL_DIRECTORIES`. If MSYS2 was installed outside `C:\msys64`, use its actual UCRT64 `bin` directory. -```cmd -python -c "from weasyprint import HTML; print('OK')" -``` +## Notes -If you see `OK`, WeasyPrint is working correctly and you can proceed with installing the remaining dependencies. +For upstream installation and native-library troubleshooting details, see the [WeasyPrint first steps documentation](https://doc.courtbouillon.org/weasyprint/latest/first_steps.html). -> **Note:** If MSYS2 was installed to a different directory (not `C:\msys64`), adjust the path in step 3 accordingly. +- PDF export uses WeasyPrint when available. The app can fall back to PyMuPDF, which may produce simpler layouts. +- DOCX export is separate from the WeasyPrint PDF dependency. +- For macOS setup, see [Prepare for macOS](./PrepareForMacUser.md). +- For the PDF export architecture, see [Technical Documentation](./TECHNICAL.md#pdf-export-dependencies). diff --git a/docs/ProjectAIWorkflows.md b/docs/ProjectAIWorkflows.md index 25536865..b1897716 100644 --- a/docs/ProjectAIWorkflows.md +++ b/docs/ProjectAIWorkflows.md @@ -1,25 +1,53 @@ -# Project-level AI Work - -Open a project through the **Project** button in the toolbar. The Explorer on -the left shows the project hierarchy. Folders load when expanded and files load -into editor tabs when selected; opening a project does not open every file. - -In the AI panel, select the **Work** tab and set the scope to **Open project**. -Project Work sends the task and a list of eligible project paths first. The model -then requests only files it needs, potentially over several steps, before it can -propose a batch of complete-file replacements. - -The panel reports inspected files, the task status, and a unified diff for every -proposed change. Selecting **Accept changes into editor** validates that every -inspected disk file is unchanged and that open editor tabs still match the task -snapshot. It then updates existing tabs or creates tabs for changed project -files. The normal Save command remains responsible for writing each reviewed -file to disk. - -Project Work reads existing UTF-8 `.md`, `.markdown`, and `.txt` files only. -It excludes hidden paths, symlinks, dependency/build directories, and paths -outside the selected project. File discovery, individual reads, total context, -provider steps, and proposed output are bounded. A task is retained in the -sidecar for one hour, can be discarded, and has separate start, step, review, -and validation operations. This separation is intended to support future -background task execution without changing the Work panel model. +# AI Panel and Notes Context + +The AI panel groups the application's document chat, AI editing, translation, provider settings, and local notes retrieval. Open it with **AI** in the toolbar. Its tabs are **Chat**, **Work**, **Translate**, and **Settings**. + +## Chat with document context + +The Chat tab sends your message along with the active document and selected text as context. Ask questions, request an explanation, or ask for a suggested edit. When the response includes an actionable document change, inspect it and choose the Apply control shown with the response. + +The chat panel also shows source labels when a response uses the configured Notes Context index. A suggested action is not applied merely because the assistant returned it; use the Apply control to make the edit. + +## Use a local Notes Context index + +Notes Context lets Chat retrieve relevant excerpts from a folder of personal or project notes. + +1. In the Chat tab, choose **Select** or **Change** beside Notes Context. +2. Browse to a local folder, or enter an absolute folder path and choose **Index**. +3. Wait for indexing to complete. The panel displays the selected folder and the number of indexed notes. +4. Use the **ON/OFF** control to include or exclude retrieved notes from Chat requests. +5. Re-index after changing the note folder's contents. Use **Clear** in the notes manager to remove indexed content and clear the saved folder selection. + +The indexer reads Markdown, Markdown-extension, and plain-text files (`.md`, `.markdown`, and `.txt`). It skips hidden folders and configured application/tool directories such as `.git`, `.obsidian`, `node_modules`, `.venv`, `dist`, and `.build`. Notes are split into chunks using headings and paragraph structure, then stored in a local SQLite database. Search uses SQLite FTS5 relevance scoring when available and a keyword-scoring fallback otherwise. The index is local; it is not a cloud vector database. + +When Notes Context is enabled, relevant excerpts retrieved from that local index are added to the AI chat prompt. Those excerpts may therefore be sent to the AI provider configured in Settings as part of the request. Local indexing does not mean that retrieved note content stays on the device after it is included in an external provider request. Check your data-handling requirements before enabling this for confidential notes. + +The notes index and its selected folder are stored in the application's per-user configuration area. The database is named `knowledge_base.db`; use the panel's **Clear** control to clear indexed content through the application. + +## Work on the active document + +In the Work tab, set **Work scope** to **Active document** and enter an instruction. Choose **Apply Changes** to run the AI editing request against the active document. The returned document content is applied to the editor if the document has not changed during the request. In the main Monaco editor, the result is applied as one editor change that can be undone through the editor's undo history. This is a direct document replacement, not a multi-file diff-review workflow. + +## Work across an open project + +Choose **Open project** in the Work scope selector to use Project Work. The AI first sees the project file list and then requests the files it needs to inspect before preparing proposed changes. The UI displays inspected files and file-by-file diffs. You review the proposal and explicitly accept it into editor tabs; it does not write to disk directly. + +See the [Project Workflows guide](./ProjectWorkflows.md) for project discovery, limits, validation, staging, and saving behavior. + +## Translation + +The Translate tab supports full-document or selection translation, Full Text or Sentence Pairs mode, progress for sentence batches, and a Stop action for an in-progress sentence translation. A stopped sentence-pair operation may leave only the batches that completed before cancellation available for review. + +Project-wide translation is also exposed in the Translate tab when a project folder is open. It translates Markdown files into a separate output tree and supports cancellation and retries for failed files. See the [Project Workflows guide](./ProjectWorkflows.md) for output paths, asset copying, and file-level behavior. + +## Provider settings and data handling + +The Settings tab configures the AI provider, model, base URL, and API key. Supported provider choices include OpenAI, Anthropic, OpenRouter, OpenAI-compatible endpoints, and local compatible services such as LM Studio and Ollama. NVIDIA and Groq are offered as OpenAI-compatible endpoint choices; Custom is available for local-compatible services. + +Provider/model preferences and the selected endpoint are stored in per-user settings. API keys can be stored using the operating-system credential store through keyring when available; environment variables are also supported. A provider may receive the active document, selected text, project excerpts, or retrieved note snippets depending on the feature and request. Only send content to external services when your data-handling rules permit it. + +## Related documentation + +- [User guide](./UserGuide.md) +- [Project workflows](./ProjectWorkflows.md) +- [Technical documentation](./TECHNICAL.md) diff --git a/docs/ProjectRoles.md b/docs/ProjectRoles.md index c02552dc..a2d103f9 100644 --- a/docs/ProjectRoles.md +++ b/docs/ProjectRoles.md @@ -18,7 +18,7 @@ project owner has granted. | Admin | [@petertzy](https://github.com/petertzy), [@lwu1822](https://github.com/lwu1822) | | Maintainer | [@Eswar0108](https://github.com/Eswar0108), [@karaaslanz](https://github.com/karaaslanz) | | Reviewer | TBD; currently review is performed by all Admins and Maintainers | -| Contributor | See [`CONTRIBUTORS.md`](../CONTRIBUTORS.md) | +| Contributor | See [CONTRIBUTORS.md](https://github.com/petertzy/markdown-reader/blob/main/CONTRIBUTORS.md) | The assignment list is current as of the latest update to this document. A person may hold more than one role when the project explicitly assigns those @@ -88,9 +88,9 @@ in the project's review capacity, not an immediate organizational change. ### Contributors For the project's contributor list, see -[`CONTRIBUTORS.md`](../CONTRIBUTORS.md). Contribution guidelines and the +[CONTRIBUTORS.md](https://github.com/petertzy/markdown-reader/blob/main/CONTRIBUTORS.md). Contribution guidelines and the process for proposing changes are documented in -[`CONTRIBUTING.md`](../CONTRIBUTING.md). +[CONTRIBUTING.md](https://github.com/petertzy/markdown-reader/blob/main/CONTRIBUTING.md). ## Adding or removing members diff --git a/docs/ProjectWorkflows.md b/docs/ProjectWorkflows.md new file mode 100644 index 00000000..bdc5b58e --- /dev/null +++ b/docs/ProjectWorkflows.md @@ -0,0 +1,73 @@ +# Project Workflows + +This guide documents the project-wide workflows implemented in Markdown Reader. These tools operate on a selected local project folder and should be used with a backup of important source files. + +## Open a project folder + +Choose **Project** in the toolbar or **File โ†’ Open Folder**. The application recursively discovers supported files below the selected folder and opens those files in editor tabs. The Explorer also displays the folder hierarchy; its subdirectories load when expanded, and selecting a file in the tree opens that file in a tab. + +Because opening a project can open many files, use a folder containing the documents you intend to work with. Project translation and Project Work use the selected folder as their root. Project Work can use the current contents of open editor tabs as input, so keep the intended project selected and save important changes before starting. + +## Translate a project + +Project translation translates Markdown files under the selected project root as one cancellable task. In the AI panel, open the **Translate** tab and use the **Translate project** controls. + +1. Open the source project folder. +2. In the Translate tab, choose the source language or leave it on **Auto Detect**, then select a target language. +3. Start **Translate project**. +4. Follow the completed/total file count, task status, and per-file results. +5. If the task finishes with failed files, choose **Retry failed files** to start a retry for only those files. +6. Open the output directory shown by the task and inspect the translated Markdown. + +Only Markdown files (`.md` and `.markdown`) are translated. Hidden folders, vendor/build folders, and symlinked directories/files are excluded from source discovery. A file larger than 1 MB is reported as failed rather than translated. A failure on one file does not prevent the remaining files from being processed. + +The source files are not modified. Results are written to a separate output tree inside the project, organized by target-language slug (for example, `translations/french/`). Relative local assets referenced by Markdown links are copied into the corresponding output tree so that translated documents can continue to resolve those assets. The output directory is excluded from future source discovery. The task can be cancelled while it is running; cancellation is cooperative between files. + +Markdown-sensitive spans are protected during translation. This includes code fences, inline code, math, HTML, URLs, link destinations and reference labels, and front matter keys. Protected content is restored after the provider responds; if required tokens are lost or invented, that file fails validation. This protection reduces structural damage but does not guarantee a perfect translation. Review the translated prose, links, copied assets, formatting, and terminology before publishing the result. + +## Use Project Work for multi-file changes + +Project Work lets the AI prepare a proposed set of edits across files in the open project. Use it for coordinated tasks such as consistent terminology changes or related documentation updates, not for silent bulk file writes. + +1. Open the relevant project folder. +2. Open the AI panel's **Work** tab and set **Work scope** to **Open project**. +3. Enter a specific instruction describing the requested changes and boundaries. +4. Let the workflow discover project paths, inspect requested files, and prepare a task summary. +5. Review the inspected-file list, every proposed file change, and each diff. +6. Choose **Accept changes into editor** only when the proposal is acceptable, or discard it to abandon the proposal. +7. Review and save each changed file from its editor tab. + +Project Work reads eligible UTF-8 `.md`, `.markdown`, and `.txt` files. It skips hidden paths, symlinks, and configured dependency/build directories. It discovers paths first; the model then requests the contents it needs in bounded steps. The workflow validates that inspected files and open buffers have not changed before applying the proposal. It does not write changes directly to project files. Applying stages the proposed content in editor tabs, where you can inspect and save it normally. + +Project Work is bounded to a maximum of 2,000 discovered files, 120 KB of request context, 12 provider steps, and a one-hour in-memory task lifetime. These limits help keep work scoped; they are not a promise that every project can be processed in one task. Task state is held by the local backend process and should not be treated as durable storage across an app/backend restart. + +## Prepare a publication from open tabs + +The **Publication** panel combines selected open document tabs into one publication draft. + +1. Open the documents to include. +2. Open the **Publication** panel from the toolbar. +3. Select the tabs and use the up/down controls to arrange their order. +4. Choose **Prepare publication** and inspect the combined draft. +5. Export the prepared result to HTML or PDF. + +Preparation is deterministic, not AI-authored. It applies the application's Markdown formatting rules, joins the selected content with separators, resolves relative image paths using each source file's directory, and generates a table of contents from the combined headings. It operates on the content in open tabs, so ensure those tabs contain the latest changes you want included. + +Publication HTML can be downloaded from browser-based development. Publication PDF export uses the desktop save-dialog flow and requires the Tauri app. Review the combined document and its image references before distribution. + +## Safety and troubleshooting + +- Keep a backup of important source documents before project-wide work. +- Do not assume translated output is publication-ready without reviewing it. +- Check per-file results when translation fails, then retry failed files if appropriate. +- Remember that opening a project can open all supported files below that folder in tabs. +- If Project Work reports that open documents changed while it was running, start the task again and inspect the fresh diffs. +- If no project is open, open a folder before starting a project-level task. +- AI operations may send document or project excerpts to the configured provider. Follow your privacy and data-handling requirements. + +## Related documentation + +- [User guide](./UserGuide.md) +- [AI panel and Notes Context](./ProjectAIWorkflows.md) +- [Technical documentation](./TECHNICAL.md) +- [Contributing guide](https://github.com/petertzy/markdown-reader/blob/main/CONTRIBUTING.md) diff --git a/docs/TECHNICAL.md b/docs/TECHNICAL.md index 8dcce431..a0cd3b81 100644 --- a/docs/TECHNICAL.md +++ b/docs/TECHNICAL.md @@ -1,7 +1,7 @@ # Technical Documentation This file contains the advanced technical details for Markdown Reader. It is -linked from the main [README](../README.MD), which is kept focused on the +linked from the main [README](https://github.com/petertzy/markdown-reader/blob/main/README.MD), which is kept focused on the project's purpose, installation, configuration, and basic usage. ## Table of Contents @@ -61,7 +61,7 @@ install the Homebrew libraries below so WeasyPrint can find `libgobject-2.0`, Pango, and Cairo: ```bash -brew install glib pango cairo libffi +brew install glib pango cairo gdk-pixbuf libffi ``` `./scripts/dev-tauri.sh` automatically adds `/opt/homebrew/lib` to @@ -73,7 +73,7 @@ For a fuller walkthrough of the macOS dependencies, including shell configuratio ### Windows PDF Export Dependencies -On Windows, WeasyPrint requires native system libraries (Cairo, Pango) that are not available by default. Install them via MSYS2 by following the steps in [PrepareForWindowsUser.md](./PrepareForWindowsUser.md). +On Windows, WeasyPrint requires native system libraries. Install the Pango runtime in MSYS2 UCRT64 and configure `WEASYPRINT_DLL_DIRECTORIES` as described in [PrepareForWindowsUser.md](./PrepareForWindowsUser.md). If WeasyPrint is unavailable, PDF export falls back to PyMuPDF with simpler layout, the same as on macOS. diff --git a/docs/UserGuide.md b/docs/UserGuide.md new file mode 100644 index 00000000..8b28d7bc --- /dev/null +++ b/docs/UserGuide.md @@ -0,0 +1,176 @@ +# User Guide + +This guide describes user-facing workflows present in the current application. The main workspace uses Monaco for Markdown source editing; Focus Mode uses a separate rich Markdown editor. + +## Contents + +- [Open and edit documents](#open-and-edit-documents) +- [Focus Mode](#focus-mode) +- [Manage files and projects](#manage-files-and-projects) +- [Preview, appearance, and document statistics](#preview-appearance-and-document-statistics) +- [AI-assisted writing and translation](#ai-assisted-writing-and-translation) +- [Configure AI providers](#configure-ai-providers) +- [Review AI changes](#review-ai-changes) +- [Import and convert files](#import-and-convert-files) +- [Tables and slash commands](#tables-and-slash-commands) +- [BibTeX citation lookup](#bibtex-citation-lookup) +- [Export and publication](#export-and-publication) +- [Troubleshooting](#troubleshooting) + +## Open and edit documents + +Markdown Reader provides a tabbed Markdown editor and rendered preview. Use **File โ†’ Open File** or the toolbar's **Open** button to select a supported document. Markdown, Markdown extensions, and plain-text files open directly. Supported non-Markdown formats are converted to Markdown when their converter is available. + +The main editor uses Monaco in Markdown mode. It supports line numbers, word wrapping, code folding, and configurable font size. The toolbar's font-size field accepts whole-number values from 8 to 72. Tabs can represent files on disk or untitled documents. Unsaved changes are indicated in the status bar. + +## Focus Mode + +Choose **Focus** in the toolbar to switch from the split Monaco-and-preview workspace to a distraction-reduced rich Markdown editor. Focus Mode uses Milkdown/Crepe with CommonMark, GitHub Flavored Markdown, math, history, and an editor slash-command menu. The Explorer and right-hand side panel are hidden while Focus Mode is active; the app toolbar and document tabs remain available. + +The Focus Mode editor handles Markdown paste separately from rich HTML clipboard content. When pasted plain text contains recognizable Markdown syntax, it can parse that text as Markdown rather than inserting visible source markers. Richly formatted HTML clipboard content remains on the normal rich-paste path. + +Use the toolbar's **Focus** control again to return to the main editor workspace. The main editor's Monaco-specific search, replace, formatting, and table shortcuts are documented in the [keyboard shortcut reference](./KeyboardShortcuts.md); not every Monaco action is available from the Focus Mode editor. + +## Manage files and projects + +Use the File menu or toolbar to create, open, save, and close document tabs. The **Project** toolbar button opens a local folder. The Explorer displays its directory tree; folders load their entries when expanded, and selecting a file opens it in a tab. + +Opening a project also recursively opens supported files under that folder into editor tabs. For a large project, this can create many tabs. The project translation and Project Work tools use the selected project folder as their scope. Close the project from the Explorer when you no longer need that folder context. + +Project operations are intended for desktop use because they require access to local folders. If a native folder picker is unavailable in a browser-based development session, the app may prompt for an absolute folder path. + +See the [Project Workflows guide](./ProjectWorkflows.md) for project translation, multi-file AI changes, and publication preparation. + +## Preview, appearance, and document statistics + +The Preview panel renders the current Markdown document so you can check headings, links, tables, code blocks, and other Markdown content while editing. Use the view controls to change the editor/preview split, show the preview, or open the rendered document in a browser. Dark mode is available from **View โ†’ Toggle Dark Mode**. + +The status bar displays the active file name, an unsaved-change indicator, word count, character count including spaces, heading count, and estimated reading time. The reading-time value is an estimate based on the application's word-count calculation. + +Keyboard shortcuts use **Command** as the primary modifier on macOS and **Ctrl** on Windows/Linux. See the [keyboard shortcuts reference](./KeyboardShortcuts.md) for the defaults and notes about the main editor versus Focus Mode. + +## AI-assisted writing and translation + +Open the **AI** toolbar panel. It contains **Chat**, **Work**, **Translate**, and **Settings** tabs. + +In Chat, ask questions about the active document or selected text. When the AI returns a proposed document action, inspect it and use the displayed Apply control to apply it. Some built-in slash commands can also be entered in the chat input. + +The Translate tab supports: + +- Translating the full active document or the current text selection. +- Full Text mode for one translation result. +- Sentence Pairs mode, which presents source and translated text in pairs and reports batch progress. +- Stopping an in-progress sentence-pair translation. A stopped task may leave only the batches completed so far in the preview. +- Applying the translation to the document/selection or inserting it below the relevant content using the available controls. + +Choose a source language or **Auto Detect**, then select a target language. Project-wide translation is also available near the top of this same Translate tab when a project folder is open; its separate file-level workflow is described in the [Project Workflows guide](./ProjectWorkflows.md). + +For local notes retrieval in Chat, see [AI panel and Notes Context](./ProjectAIWorkflows.md). For active-document Work and project Work, see [Review AI changes](#review-ai-changes) and the [AI panel guide](./ProjectAIWorkflows.md). + +## Configure AI providers + +Open the AI panel's **Settings** tab to configure the provider, model, endpoint, and credentials. Available choices include OpenAI, Anthropic, OpenRouter, and OpenAI-compatible endpoints. The **Local** provider supports compatible servers such as LM Studio and Ollama, as well as a custom endpoint. + +For an OpenAI-compatible endpoint, select one of the configured base URL choices, such as NVIDIA or Groq. For the Local provider, choose LM Studio, Ollama, or Custom. A custom endpoint needs its base URL before you can fetch its model list. Use **Fetch Models** to query the selected endpoint when the control is available, then choose and save the model. + +Provider and model preferences are stored in the per-user settings file. API keys can be stored in the operating-system credential store through keyring when available; environment variables can also provide credentials. The Settings tab reports whether a key is saved, supplied by the environment, or unavailable. Local endpoints usually do not need an API key unless the server is configured to require one. + +Provider model availability, API behavior, rate limits, and costs are controlled by the provider. Multi-provider failover depends on configured fallback providers and on the type of error returned; it is not a guarantee that every request will succeed. + +## Review AI changes + +The application has more than one AI editing path: + +- **Chat suggestions:** When Chat returns an actionable suggestion, the panel displays an Apply control. Inspect the suggestion before applying it. +- **Active-document Work:** In the Work tab, choose **Active document**, enter an instruction, and choose **Apply Changes**. The returned replacement is applied to the active document if that document has not changed while the request was running. In the main Monaco editor, the result is applied as one editor change that can be undone through the editor's undo history; it is not a separate multi-file diff review. +- **Project Work:** Choose **Open project** in the Work scope selector. The AI inspects requested project files and prepares proposed changes with file-by-file diffs. Review the diffs before selecting **Accept changes into editor**. Applying stages the contents in editor tabs; it does not write the files directly to disk. Save the reviewed tabs when ready. + +Project Work has its own validation and staging behavior; see [Project Workflows](./ProjectWorkflows.md). + +## Import and convert files + +Markdown Reader opens Markdown and plain text directly. The backend handles HTML, PDF, and DOCX through native converters. Additional formats are converted through the optional Microsoft MarkItDown integration. Supported extensions include: + +| Category | Formats | +| --- | --- | +| Text and web | Markdown, TXT, HTML | +| Documents | PDF, DOCX | +| Office and data | PPT, PPTX, XLS, XLSX, CSV | +| Structured and e-book | EPUB, XML | +| Archives | ZIP | +| Image and OCR | JPG, JPEG, PNG, GIF, BMP, TIFF | +| Audio | WAV, MP3 | +| Other | Outlook MSG, Jupyter IPYNB | + +MarkItDown availability depends on the installed optional dependencies. Normal PDF opening uses PyMuPDF. Docling is available through a separate backend conversion endpoint, but the current frontend does not expose it as a selectable PDF-import mode. Conversion can lose layout or information, particularly with scanned PDFs, complex tables, images, and Office documents. Inspect the resulting Markdown before using it as a source of truth. + +The project currently requires Python 3.11 to 3.13; Python 3.14 is excluded because some optional MarkItDown dependencies do not yet provide compatible wheels. + +## Tables and slash commands + +Use **Table โ†’ Insert Table** or the `/insert-table` slash command to create a Markdown table. The main editor's table command inserts a local Markdown table and does not require an AI request. + +In the main editor, type `/` at the start of a line or after whitespace to open the slash-command menu: + +| Command | Result | +| --- | --- | +| `/summarize` | Summarizes the document with AI | +| `/translate` | Opens the Translate tab in the AI panel | +| `/format` | Formats text with AI | +| `/toc` | Generates a table of contents with AI | +| `/fix-code` | Cleans up Markdown code fences with AI | +| `/insert-table` | Inserts a table locally | +| `/insert-toc` | Builds a table of contents locally from document headings | + +Use the arrow keys to select a command, Enter to execute it, and Escape to close the menu. Focus Mode has its own editor slash menu for the available commands. + +## BibTeX citation lookup + +The Cite panel can load a BibTeX `.bib` library. Search entries by citation key, author, title, year, publication venue, or entry type, then choose an entry to insert a citation-key marker such as `[@doe2024]` at the editor cursor. + +In the desktop app, use **Select** to choose a BibTeX file with the native file picker. In browser-based development, the selected file is uploaded to the local backend and becomes the active citation library. + +The current feature is a BibTeX entry browser and citation-key insertion helper. Do not assume that the app generates a formatted bibliography or converts citation markers into a publication-style reference list during export; review and complete the citation workflow required by your target publication separately. + +## Export and publication + +The toolbar's export controls support HTML, PDF, and DOCX for the current document. In the desktop app, the save dialog lets you choose the output path. Browser-based development supports direct HTML download; PDF and DOCX export require the desktop save-dialog flow. + +PDF export uses WeasyPrint when its native dependencies are available and can fall back to PyMuPDF with simpler layout. See [Technical documentation](./TECHNICAL.md#pdf-export-dependencies), [macOS setup](./PrepareForMacUser.md), and [Windows setup](./PrepareForWindowsUser.md). + +The **Publication** panel combines selected open document tabs into a publication draft. Select the tabs, arrange their order, and prepare the draft. The backend applies deterministic formatting, resolves relative image paths against each source document's folder, and generates a table of contents from the combined headings. This is not an AI editorial workflow. Inspect the combined result before export. Publication HTML can be downloaded in browser development; publication PDF export requires the desktop app. + +For multi-file publication details, see [Project Workflows](./ProjectWorkflows.md). + +## Troubleshooting + +### The app does not start + +Check the Python and Node.js versions, install the prerequisites in the main [README](https://github.com/petertzy/markdown-reader/blob/main/README.MD), and make sure `frontend/.env.local` exists. Run the platform-appropriate development helper from the repository root. + +### The backend port is already in use + +The development helper starts with port 8000 and tries nearby ports if it cannot bind the requested port. Check the helper's output for the actual backend port. To request a port, set `MARKDOWN_READER_BACKEND_PORT` before launching it. + +### AI requests fail + +Confirm the selected provider, model, endpoint, and credentials. Local model servers must be running and reachable at the configured URL. Check provider-specific limits and errors; fallback behavior depends on the configured providers and error type. + +### PDF export has missing libraries or layout differences + +Install the native dependencies described in the platform-specific setup guide. If WeasyPrint cannot load, the app may use the PyMuPDF fallback, which can produce simpler layouts. + +### Import results are incomplete + +Some conversions depend on optional third-party packages and on the structure of the source file. Confirm that the relevant dependencies are installed and inspect the converted Markdown, especially for complex PDFs, scanned images, tables, and Office documents. + +## Related documentation + +- [AI panel and Notes Context](./ProjectAIWorkflows.md) +- [Project workflows](./ProjectWorkflows.md) +- [Keyboard shortcuts](./KeyboardShortcuts.md) +- [Technical documentation](./TECHNICAL.md) +- [macOS setup](./PrepareForMacUser.md) +- [Windows setup](./PrepareForWindowsUser.md) +- [Code signing and distribution](./CodeSigningAndDistribution.md) +- [Contributing guide](https://github.com/petertzy/markdown-reader/blob/main/CONTRIBUTING.md) diff --git a/docs/index.md b/docs/index.md index 4b2c01c2..1209dd4a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,341 +1,40 @@ -# Markdown Reader +# Documentation Index -Markdown Reader is a modern Markdown editor/reader with real-time preview support, AI-assisted editing, and desktop packaging through Tauri. It uses a Next.js frontend with a local FastAPI backend. +Use this page to find the right guide. User-facing instructions describe workflows present in the current application. Feasibility studies, strategy notes, and cost comparisons may describe proposals or historical snapshots rather than the current implementation. ---- +## Start here -## Features +- [Main README](https://github.com/petertzy/markdown-reader/blob/main/README.MD): project overview, desktop downloads, source setup, and links to detailed guides. +- [User Guide](./UserGuide.md): editor modes, file handling, AI assistance, importing, citations, and export. +- [AI Panel and Notes Context](./ProjectAIWorkflows.md): Chat, active-document Work, project Work, local note indexing, and provider/data handling. +- [Project Workflows](./ProjectWorkflows.md): project translation, multi-file AI changes, and publication drafts. +- [Keyboard Shortcuts](./KeyboardShortcuts.md): default application and editor shortcuts. +- [Contributing Guide](https://github.com/petertzy/markdown-reader/blob/main/CONTRIBUTING.md): prerequisites, development setup, validation, and contribution workflow. -* Tabbed Markdown editing with real-time HTML preview. -* **AI-Powered Translation**: Translate Markdown documents while preserving formatting (supports OpenAI Compatible, OpenRouter, OpenAI, and Anthropic). -* **Built-in AI Agent Chat**: A dockable in-app chat panel can read current document context and suggest/apply edits. -* **AI Task Automation Templates**: Run reusable templates for formatting, TOC generation, summaries, and code-block cleanup. -* **Approval/Reject Workflow**: Every AI-proposed change can be explicitly applied or rejected from the panel. -* **AI Audit Trail**: Proposed/applied/rejected/undone AI actions are logged for auditing and rollback tracking. -* **API Key Management**: Missing or rejected provider keys trigger an in-app dialog, and keys are saved in the OS credential store. -* **Progressive Translation Rendering**: Long translations are split into smaller chunks, inserted into the editor as they complete, auto-scrolled into view, and tracked with a progress bar. -* Dark mode toggle. -* **Advanced Table Editor**: Interactive table insertion with customizable rows and columns. -* **Dual PDF Conversion**: Fast PyMuPDF mode or advanced [Docling](https://github.com/docling-project/docling) mode for complex documents. -* Built with Next.js, Tauri, and a local FastAPI backend. -* Opens preview automatically and avoids multiple browser tabs for a smoother experience. -* Multi-provider AI failover: Automatically switches to fallback providers on rate-limit/auth/server errors. +## User and platform guides ---- +- [Prepare for macOS](./PrepareForMacUser.md): Homebrew libraries used by WeasyPrint for PDF export. +- [Prepare for Windows](./PrepareForWindowsUser.md): MSYS2 UCRT64 libraries and DLL discovery for WeasyPrint. +- [Math Rendering Test File](./MathRenderingTestFile.md): sample content for checking mathematical notation rendering. -## Editor Overview +## Architecture and implementation -Image +- [Technical Documentation](./TECHNICAL.md): architecture, local backend security, desktop content security policy, PDF export dependencies, and local packaging. +- [Code Signing and Distribution](./CodeSigningAndDistribution.md): current release workflow status and platform-signing research. ---- +## Project governance -## Preview Overview +- [Project Roles](./ProjectRoles.md): project responsibilities and role assignments. -Image +## Hosting and planning notes ---- +- [Hosting Strategy](./HostingStrategy.md): historical Cloudflare Pages proposal, with a note on the current GitHub Pages distribution deployment. +- [AI Work Panel Feasibility Study](./AIWorkPanelFeasibilityStudy.md): design exploration, not a guarantee that each proposal is implemented. +- [Project Extensions Feasibility Study](./ProjectExtensionsFeasibilityStudy.md): extension concepts and planning notes. -## Installation & Usage +## Maintenance notes -#### 1. Clone the repository - -```bash -git clone https://github.com/petertzy/markdown-reader.git -cd markdown-reader -``` - -#### 2. Create a virtual environment (recommended) - -```bash -python -m venv .venv -source .venv/bin/activate # macOS/Linux -# .\.venv\Scripts\activate # Windows (cmd/powershell) -``` - -#### 3. Install dependencies - -For Mac users, you should first complete the preparation steps described in the [PrepareForMacUser](./doc/PrepareForMacUser.md) file. - -For Windows users, WeasyPrint requires additional system libraries. Complete the preparation steps described in the [PrepareForWindowsUser](./doc/PrepareForWindowsUser.md) file before installing dependencies. - -With [uv](https://docs.astral.sh/uv/) (recommended): - -```bash -uv sync --python 3.14 -source .venv/bin/activate -``` - -If you update dependencies in `pyproject.toml`, regenerate and commit the lockfile: - -```bash -uv lock -``` - -CI uses `uv sync --locked --extra dev`, so `uv.lock` must stay in sync with `pyproject.toml`. - -Or with pip: - -```bash -pip install . -``` - -#### 4. Install pre-commit hooks (recommended) - -This project uses [pre-commit](https://pre-commit.com/) to automatically fix import sorting and code formatting on every commit. Run this once after cloning: - -```bash -pre-commit install -``` - -After this, `ruff --fix` and `ruff-format` will run automatically on staged files whenever you `git commit`. - ---- - -## Running the Application - -```bash -uv run ./scripts/dev-tauri.sh -``` - -### How to Use - -* **Open File**: Choose `.md`, `.markdown`, `.html`, `.htm`, or `.pdf` from the "File โ†’ Open File" menu. -* **Open with Double-Click**: Double-clicking a `.md` file opens it directly with the app and displays the document with a real-time preview. -* **Editor-Only Mode**: To open a `.md` file in the editor without automatically generating a web preview, configure the double-click behavior via "Settings โ†’ Open Behavior โ†’ Editor Only". -* **Dark Mode**: Toggle via "View โ†’ Toggle Dark Mode". -* **Preview**: Automatically opens in your web browser, only one tab is opened per session. -* **AI Translation**: - - Translate selected text: "Edit โ†’ Translate with AI โ†’ Translate Selected Text with AI" - - Translate full document: "Edit โ†’ Translate with AI โ†’ Translate Full Document with AI" - - Select source and target languages from dropdown menus - - Configure provider/model/API keys: "Settings โ†’ AI Provider & API Keys..." - - If a key is missing or rejected, the app prompts for the correct provider key and stores it in the OS credential store - - Large translations appear progressively in the editor with automatic scrolling and a visible progress bar -* **AI Agent Chat Panel**: - - Show/hide: "View โ†’ Show AI Agent Panel" - - You can type natural-language requests directly in the chat box; no special command syntax is required - - The AI agent can automatically prepare edit suggestions for tasks such as summaries, formatting, TOC generation, and code-block fixes - - Typical chat requests: - - `generate summary` - - `generate table of contents` - - `format this section` - - `format code blocks and correct syntax` - - Supports commands like "format this section", "generate summary", and "generate table of contents" - - Built-in automation templates can trigger repetitive editor tasks quickly - - Can format and fix Markdown code blocks (including unclosed fences) - - Context scope toggle: "Full document" or "Selection only" - - Uses current document and/or selected text as context based on the selected scope - - Workflow: send a natural-language request -> review AI preview -> click "Apply Suggestion" to apply - - AI suggestions can be applied or rejected with confirmation and validation checks - - "Undo AI Task" allows one-click rollback of the latest applied AI change - - "Audit Log" shows recent AI automation events for traceability - - Chat history is stored per document and restored automatically -* **Table Insertion**: Use "Table โ†’ Insert Table" to create custom tables with interactive cell editing. -* **PDF Conversion Modes**: - - Fast mode (default): Uses PyMuPDF for quick extraction - - Advanced mode: Enable "Tools โ†’ Use Advanced PDF Conversion (Docling)" for complex documents - - View mode info: "Tools โ†’ PDF Converter Info" - ---- - -## Packaging as a macOS App (Optional) - -Build the backend sidecar and Tauri desktop bundle: - -```bash -uv run pyinstaller markdown-reader-backend.spec -cd frontend -npm run tauri build -``` - -The generated desktop artifacts are produced by Tauri under `frontend/src-tauri/target/release/bundle/`. - ---- - -## Exit the Virtual Environment -```bash -deactivate -``` - -## Code Formatting (Ruff) - -This project uses **Ruff** to ensure consistent code formatting across all contributions. - -Before submitting changes, please check and format your code. - -### Check formatting - -```bash -uv run ruff format --check . -``` - -If any files are not properly formatted, you will see output like: - -```text -Would reformat: some_file.py -``` - -This means the file does not match the required formatting style. - -### Fix formatting - -To automatically format all files: - -```bash -uv run ruff format . -``` - -## Running Tests - -The project uses Python's built-in `unittest` framework. Tests live in the `tests/` directory and cover AI automation logic, UI helper methods, provider configuration, and agent interaction workflows. - -Run the full test suite: - -```bash -uv run python -m unittest discover -s tests -``` - -Or with pip: - -```bash -python -m unittest discover -s tests -``` - -Run a single test file: - -```bash -uv run python -m unittest tests/test_ai_automation_logic.py -``` - -### Test coverage overview - -| Test file | What it covers | -|---|---| -| `test_ai_automation_logic.py` | Offline fallback logic for TOC generation, summarization, code-block formatting, and task template listing | -| `test_ai_provider_config_logic.py` | Provider configuration and API key management logic | - -Tests run automatically on every push and pull request via GitHub Actions (see `.github/workflows/python-ci.yml`). - -> **macOS note:** PDF export uses WeasyPrint, which requires native system libraries (pango, cairo, gdk-pixbuf). If you see an `OSError: cannot load library 'libgobject-2.0-0'` error, follow the steps in [PrepareForMacUser.md](./PrepareForMacUser.md) first. - ---- - -## Development Workflow: uv vs. pip / requirements.txt - -This project previously used a `requirements.txt` file and standard `pip` commands. It has since migrated to [`uv`](https://docs.astral.sh/uv/) with `pyproject.toml`. Here is what changed and why. - -### The old approach (requirements.txt + pip) - -```bash -python -m venv .venv -source .venv/bin/activate -pip install -r requirements.txt -``` - -`requirements.txt` is a flat list of pinned packages. It works, but has limitations: - -- No distinction between direct dependencies and transitive ones โ€” everything is listed together. -- No separation of dev-only dependencies (linters, test runners) from runtime dependencies. -- No built-in lockfile mechanism โ€” the file must be manually regenerated and tends to drift. -- `pip` resolves the full dependency graph from scratch on every install, which is slow. - -### The new approach (pyproject.toml + uv) - -```bash -uv sync # install all runtime dependencies from the lockfile -uv sync --locked --extra dev # also install dev tools (ruff, ty, pre-commit) -``` - -`pyproject.toml` is the modern Python packaging standard (PEP 517/518/621). It consolidates project metadata, runtime dependencies, and tool configuration in one file. Key benefits over `requirements.txt`: - -- **Dependency groups**: runtime deps go under `[project.dependencies]`; dev-only tools (Ruff, ty, pre-commit) go under `[project.optional-dependencies] dev`; docs tools under `docs`. You only install what you need. -- **Lockfile (`uv.lock`)**: records exact versions of every direct and transitive package. `uv sync --locked` guarantees identical environments across all machines and in CI โ€” no more "works on my machine" surprises. -- **Speed**: `uv` is written in Rust and resolves and installs packages significantly faster than `pip`. -- **Single source of truth**: tool configuration for Ruff, ty, and isort also lives in `pyproject.toml`, eliminating separate config files. - -### When to update the lockfile - -If you add or change a dependency in `pyproject.toml`, regenerate the lockfile and commit it: - -```bash -uv lock -git add pyproject.toml uv.lock -git commit -m "chore: update dependencies" -``` - -CI runs `uv sync --locked`, so a stale `uv.lock` will fail the build โ€” this is intentional and keeps the lockfile honest. - ---- - -## Submit Changes to Git -```bash -git add . -git commit -m "Update" # Replace "Update" with a meaningful commit message -git push -``` - -## Technical Details - -* Frontend: Next.js and Tauri -* Backend: FastAPI sidecar process -* Markdown Engine: `markdown2` -* HTML Preview: Rendered in the desktop UI -* File Conversion: `html2text` for HTML, `PyMuPDF` and `docling` for PDF import (`pypdf` is used as a fallback when PyMuPDF is unavailable) -* PDF Export: `weasyprint` -* AI Translation: `requests` for API communication with OpenAI Compatible, OpenRouter, OpenAI, and Anthropic -* Configuration: Per-user settings JSON for provider/model (macOS `~/Library/Application Support/MarkdownReader/settings.json`; Windows `%APPDATA%/MarkdownReader/settings.json`; Linux `~/.config/markdown-reader/settings.json`) plus OS credential storage for API keys (`keyring`) -* Auto-failover: Automatically switches AI providers when the primary provider returns rate-limit/auth/server errors - ---- - -## System Requirements: -Python >= 3.10 - ---- - -## AI-powered translation: -To enable AI-powered translation features, you need to set up API keys: - -1. Open `Settings -> AI Provider & API Keys...`. -2. Choose provider and model. -3. Enter API key and save. -4. If you choose `OpenAI Compatible`, you can also choose a Base URL option (`NVIDIA` or `Groq`). - -The app stores provider and model in a per-user JSON file: - -- macOS: `~/Library/Application Support/MarkdownReader/settings.json` -- Windows: `%APPDATA%/MarkdownReader/settings.json` -- Linux: `~/.config/markdown-reader/settings.json` - -**How to get API keys:** -- **OpenRouter** (recommended for free tier): [openrouter.ai](https://openrouter.ai/) -- **OpenAI**: [platform.openai.com](https://platform.openai.com/) -- **Anthropic**: [console.anthropic.com](https://console.anthropic.com/) -- **OpenAI Compatible**: Create an API key from your chosen compatible provider console, then select the matching Base URL preset in this app: - - **NVIDIA preset**: [NVIDIA Integrate](https://build.nvidia.com/) - - **Groq preset**: [Groq Console](https://console.groq.com/keys) - -API keys are saved in the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service/KWallet on Linux when available). - -The app will automatically switch to a fallback provider when the primary provider returns rate-limit/auth/server errors. - ---- - -## License - -This project is licensed under the **MIT License**. -See the [LICENSE](LICENSE.md) file for the full text. - ---- - -## Contributing - -All contributions are welcome, including: - -- Bug reports -- Feature suggestions -- Pull requests -- Documentation improvements -- Distribution and hosting setup: see [HostingStrategy](./HostingStrategy.md) - -Please see our [CONTRIBUTING](CONTRIBUTING.md) guide for more details on how to get started, submit changes, or report issues. +- Keep user instructions aligned with visible controls and implemented backend behavior. +- Update the detailed guide closest to a changed workflow, then update README only when the change belongs in the concise overview. +- Link to one source of truth rather than duplicating long procedures. +- Clearly label planning, feasibility, or historical research so it is not mistaken for shipped behavior. diff --git a/mkdocs.yml b/mkdocs.yml index 2803af20..518ffde2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,13 +1,20 @@ site_name: Markdown Reader Docs + theme: - name: material + name: material nav: - - Home: index.md + - Home: index.md + - User Guide: UserGuide.md + - AI Panel and Notes Context: ProjectAIWorkflows.md + - Project Workflows: ProjectWorkflows.md + - Keyboard Shortcuts: KeyboardShortcuts.md + - Technical Documentation: TECHNICAL.md - Project Roles and Responsibilities: ProjectRoles.md - Math Rendering Test File: MathRenderingTestFile.md - - Prepare For Mac User: PrepareForMacUser.md - - Prepare For Windows User: PrepareForWindowsUser.md - - AI Work Panel Feasibility Study: AIWorkPanelFeasibilityStudy.md - - Code Signing & Distribution: CodeSigningAndDistribution.md + - Prepare for macOS: PrepareForMacUser.md + - Prepare for Windows: PrepareForWindowsUser.md + - Code Signing and Distribution: CodeSigningAndDistribution.md - Hosting Strategy: HostingStrategy.md + - AI Work Panel Feasibility Study: AIWorkPanelFeasibilityStudy.md + - Project Extensions Feasibility Study: ProjectExtensionsFeasibilityStudy.md