docs: add user guide

.github/workflows/mdbook.yml

@@ -0,0 +1,55 @@
+name: Deploy mdBook site to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    env:
+      MDBOOK_VERSION: 0.5
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Install mdBook
+        run: |
+          cargo install --version ${MDBOOK_VERSION} mdbook
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+      - name: Build with mdBook
+        run: mdbook build docs/user-guide
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/user-guide/book
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -26,6 +26,9 @@
 # Debug artifacts
 *.dSYM/
 
+# mdBook build output
+docs/user-guide/book/
+
 # profiling data
 *.profraw
 *.profdata

docs/user-guide/book.toml

@@ -0,0 +1,8 @@
+[book]
+title = "ELNPack User Guide"
+authors = ["ELNPack Team"]
+language = "en"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "ayu"

docs/user-guide/src/SUMMARY.md

@@ -0,0 +1,12 @@
+# Table of Contents
+
+- [Introduction](./introduction.md)
+- [Install & Launch](./installation.md)
+- [Quick Workflow](./quickstart.md)
+- [UI Overview](./overview.md)
+  - [Markdown Editor](./markdown.md)
+  - [Attachments](./attachments.md)
+  - [Keywords](./keywords.md)
+  - [Metadata](./metadata.md)
+  - [Date & Time Picker](./datetime.md)
+  - [Saving ELN Archives](./saving.md)

docs/user-guide/src/attachments.md

@@ -0,0 +1,17 @@
+# Attachments
+
+![File Attachment](images/ui-file-attachments.webp)
+
+1. Click **Add files** to open the file picker. Select all files you want to attach.
+2. A thumbnail will be shown for each file if possible.
+3. Use the **Edit** button to rename files directly from the list.
+4. If a file has been automatically renamed, this will be indicated by a warning icon. Hover the icon to see the original name.
+5. To delete files, click the **Delete** button next to each file.
+6. Beneath the filename, **additional information** such as file size, MIME type and SHA256 hash are displayed.
+
+> [!TIP]
+> Files are hashed twice: first when adding an attachment, and again when saving
+> the ELN archive. If the hashes do not match, an error message is shown.
+>
+> This helps ensure that files are not modified in between and that the file
+> saved in the archive is identical to the one you attached.

docs/user-guide/src/datetime.md

@@ -0,0 +1,11 @@
+# Date & Time Picker
+
+![Date & Time Picker](./images/ui-datetime-picker.webp)
+
+- Pick the calendar date and clock time of the experiment.
+- You can click on the **Now** button to use the current date and time.
+- The chosen value is stored in the archive metadata.
+- During a later ELN import, this exact timestamp is used as creation date.
+
+> [!TIP]
+> Backfill older experiments by setting the original date and time.

docs/user-guide/src/installation.md

@@ -0,0 +1,102 @@
+# Install & Launch
+
+## Easiest: download the release binary
+
+1. Go to the project’s Releases page on GitHub.
+2. Download the asset for your platform (Windows, macOS, or Linux) and CPU (x86_64, i686, or aarch64/arm64).
+3. Extract the archive and run the executable.
+
+### Windows (10+)
+
+> [!IMPORTANT]
+> Binaries are not code-signed; if SmartScreen appears, choose “More info” → “Run anyway”.
+
+1. Download the Windows `.zip` (x86_64 or i686):
+   - `elnpack-x86_64-pc-windows-msvc.zip` (64-bit)
+   - `elnpack-i686-pc-windows-msvc.zip` (32-bit)
+2. Extract it (right-click → Extract All…).
+3. Double-click `elnpack.exe`.
+   - If the Universal CRT is missing, install the latest VC++ Redistributable (x64 or x86).
+
+### macOS (Intel & Apple Silicon)
+
+> [!IMPORTANT]
+> Binaries are not code-signed; if Gatekeeper blocks execution, using “Open” once will allow it to run.
+
+1. Download the macOS `.tar.gz` matching your Mac:
+   - Apple Silicon → `elnpack-aarch64-apple-darwin.tar.gz`
+   - Intel → `elnpack-x86_64-apple-darwin.tar.gz`
+2. Double-click to extract (or run `tar -xzf elnpack-*.tar.gz`).
+3. In Finder, right-click the `elnpack` app/binary → Open → confirm.
+
+### GNU/Linux
+
+1. Download the Linux `.tar.gz` for your CPU (x86_64, i686, or aarch64):
+   - `elnpack-x86_64-unknown-linux-gnu.tar.gz`
+   - `elnpack-i686-unknown-linux-gnu.tar.gz`
+   - `elnpack-aarch64-unknown-linux-gnu.tar.gz`
+2. Extract and run:
+
+```bash
+tar -xzf elnpack-<version>-<arch>-unknown-linux-gnu.tar.gz
+cd elnpack-<version>
+chmod +x elnpack
+./elnpack
+```
+
+3. Needs glibc ≥ 2.31 (e.g., Ubuntu 20.04+). On minimal systems ensure `libc6`, `libgcc-s1`, and `libm` exist.
+
+## Build from source
+
+### Prerequisites
+
+- [Installed](https://www.rust-lang.org/tools/install) and working stable Rust compiler toolchain (≥ 1.85.0; Rust 2024)
+- You intend to build for a [supported build target](https://doc.rust-lang.org/beta/rustc/platform-support.html).
+
+### Build & Run
+
+Building and running ELNPack from source is straightforward. Ensure you have the prerequisites in place and follow these steps:
+
+```bash
+# Clone the repository
+git clone https://github.com/Athemis/ELNPack.git && cd ELNPack
+# Compile and run a debug build
+cargo run
+# Compile and run a release build
+cargo run --release
+```
+
+#### Windows 7
+
+> [!IMPORTANT]
+> Windows 7 is a so-called _[Tier 3](https://doc.rust-lang.org/beta/rustc/target-tier-policy.html#tier-3-target-policy)_ build target, which means it is **not officially supported** by Rust. Our testing has shown that it is possible to build and run ELNPack on Windows 7, however there are some known issues with the Windows 7 build target ([see below](installation.md#known-issues)).
+>
+> Furthermore, building requires a nightly toolchain.
+
+The `*-win7-windows-msvc` targets can only be built on Windows and need the [MSVC BuildTools](https://visualstudio.microsoft.com/en/downloads). If you have problems compiling or running the produced binary, try installing an older version of the BuildTools such as `MSVC v140 - VS 2015 C++ build tools (v14.00)` from the installer. Make sure to install the `Windows SDK` as well.
+
+Unfortunately, the `*-win7-windows-gnu` targets which in theory would allow cross compilation and are not dependent on the MSVC BuildTools, produce binaries that are not compatible with Windows 7 due to the lack of certain system libraries.
+
+```bash
+# Install Rust Nightly Toolchain
+rustup toolchain install nightly
+rustup component add rust-src --toolchain nightly
+
+# The MSVC targets can only be built on Windows and need the MSVC BuildTools:
+# https://visualstudio.microsoft.com/en/downloads
+
+# Build binaries; use your desired target
+# cargo +nightly build -Z build-std --target x86_64-win7-windows-msvc
+cargo +nightly build -Z build-std --target i686-win7-windows-msvc
+```
+
+##### Known Issues
+
+> [!NOTE]
+> Limited testing was performed in **virtualized** Windows 7 systems due to a lack of physical hardware running this OS.
+>
+> Some or all of the following issues may be solely caused by the state of virtualized graphics hardware driver support and may or may not be absent on real hardware.
+
+- The **mouse pointer** is off by a significant amount. While the application remains functional, you may have a hard time hitting the intended interface elements.
+- There were **severe graphical distortions**, when the window is not maximized. Work around this by maximizing the window before interacting with it.
+- The application will not launch without functional **OpenGL support** due to requirements of the underlying user interface library.

docs/user-guide/src/introduction.md

@@ -0,0 +1,36 @@
+# Introduction
+
+ELNPack is a desktop app for creating [ELN archives](https://the.elnconsortium.org) you can import into ELNs like eLabFTW. Everything runs locally—no network access required. This guide shows how to install, record an experiment, attach your data, and export the archive.
+
+> [!TIP]
+> Do all of this entirely **offline**. Ideal for use in labs with limited network access:
+>
+> Copy the ELN archive to a USB drive and import it into eLabFTW from another computer with proper network access.
+
+## Prerequisites
+
+- Prebuilt binaries are available for:
+  - **Windows 10+** on **x86_64**, and **arm64**
+  - **macOS** on **x86_64**, and **arm64**
+  - **GNU/Linux** on **x86**, **x86_64**, and **arm64**.
+- For other operating systems or architectures, you can
+  [build ELNPack from source](installation.md#optional-build-from-source-developers).
+- For a full list of supported OS and CPU combinations, see
+  [Rust Platform Support](https://doc.rust-lang.org/beta/rustc/platform-support.html).
+
+> [!WARNING]
+> Windows XP and earlier are **not supported**. Supporting very old and current
+> operating systems at the same time is difficult due to missing APIs, libraries,
+> and compiler support.
+>
+> There is limited compiler support for Windows 7. You can try to
+> [build ELNPack for Windows 7](installation.md#build-for-windows-7) yourself.
+
+## What you can do
+
+- Set the experiment date/time.
+- Write experiment notes in the Markdown editors.
+- Add keywords to your experiment.
+- Describe your experiment using metadata. Import existing metadata from eLabFTW extra field JSON files.
+- Attach arbitrary files.
+- Export an ELN archive compatible with eLabFTW.

docs/user-guide/src/keywords.md

@@ -0,0 +1,12 @@
+# Keywords
+
+![Keywords](images/ui-keywords.webp)
+
+1. Add short search terms (e.g., technique, instrument, sample ID) to make entries easier to find after import.
+2. Delete by clicking the trash icon.
+3. Edit inline by clicking on the keyword.
+
+> [!TIP]
+>
+> - Comma-separated import is supported by pasting a list: `microscopy, TEM, project A`.
+> - Keywords are automatically deduplicated.

docs/user-guide/src/markdown.md

@@ -0,0 +1,26 @@
+# Markdown Editor
+
+![Markdown Logo](images/ui-markdown-editor.webp)
+
+1. Toolbar buttons insert Markdown at the cursor. From left to right:
+   - Headings (Dropdown): `# H1`…`# H6`
+   - Bold: `**bold**`
+   - Italic: `*italic*`
+   - Strikethrough: `~~strikethrough~~`
+   - Underline: `__underline__`
+   - Code (Dropdown): inline and block code
+   - Lists (Dropdown): `* list item` and `1. numbered list item`
+   - Links: `[link text](url)`
+   - Blockquote: `> blockquote`
+   - Images: `![alt text](url)`
+   - Tables: `| header | header |`…`| row | row |`
+   - Horizontal Rule: `---`
+   - Math (Dropdown): inline `$\math$` and block `$$\math$$`
+2. Use the editor for the experiment description, steps, and results. The resulting Markdown is by default converted to HTML when exporting the ELN archive.
+
+> [!TIP]
+> - You can use all features of [CommonMark](https://commonmark.org) with some additional Markdown extensions like tables and math.
+> - Use raw HTML in the Markdown code for more advanced formatting. Keep in mind though that HTML is sanitized when exporting the ELN archive to prevent XSS attacks which may remove **potentially unsafe** HTML tags (e.g., `<script>`).
+
+> [!NOTE]
+> Currently the **image insertion** feature is ignorant of your file attachments. You can however use it to reference external images by providing their URLs.

docs/user-guide/src/metadata.md

@@ -0,0 +1,21 @@
+# Metadata
+
+![Metadata Overview](images/ui-metadata-overview.webp)
+
+1. **Add groups** and metadata **fields** by clicking the respective buttons.
+2. **Edit** existing groups or **delete** them.
+3. **Fill in** the fields with appropriate values.
+4. **[Edit](metadata.md#edit-field-properties)** or **delete** fields. This includes changing the label or options.
+
+> [!TIP]
+> Field types cannot be changed after creation. To change a field type, you must delete the field and recreate it with the desired type.
+
+## Edit field properties
+
+![Edit metadata field](images/ui-metadata-edit-field.webp)
+
+Here you can change the **title** (1) and **description** (2) of a metadata field. You can also choose whether the field is **required**, read-only and other **settings** which are specific to the field type (3). In some cases such as selection fields or numeric fields, **options** can be added or removed (4).
+
+Finally, you can also change the assigned **group** of the field (5).
+
+Click **Save** to apply your changes.

docs/user-guide/src/overview.md

@@ -0,0 +1,14 @@
+# UI Overview
+
+![ELNPack UI overview](./images/ui-overview.webp)
+
+Key areas on the screen:
+
+1. **[ELN export controls](saving.md)**: Switch between export formats of the main text HTML (default) and Markdown; Button to save the final ELN archive.
+2. **Title**: enter a short title.
+3. **Type**: choose the entry type (Experiment/Resource). Defines the type of the entry when imported into eLabFTW.
+4. **[Performed at](datetime.md)**: set date, time, and timezone (local time shown; stored as UTC).
+5. **[Main text](markdown.md)**: editor with toolbar for headings, emphasis, lists, links, code, superscript/subscript, tables, and math.
+6. **[Keywords](keywords.md)**: add comma-separated keywords via the dialog.
+7. **[Metadata](metadata.md)**: add structured metadata; import from eLabFTW extra fields JSON or create from scratch. Will be exported as eLabFTW compatible extra fields in the final ELN archive.
+8. **[Attachments](attachments.md)**: attach files to the archive. Filenames will be automatically sanitized and checked for duplicates. File content is hashed and checked for integrity and possible duplicates.

docs/user-guide/src/quickstart.md

@@ -0,0 +1,12 @@
+# Quick Workflow
+
+Follow these steps after your experiment to create an ELN archive you can import into eLabFTW or other ELN tools.
+
+1. Launch the app (`cargo run` or open your packaged binary).
+2. **Write your notes** in the [Markdown editor](markdown.md).
+3. **Add files** in the [Attachments list](attachments.md): raw data, images, scripts. Rename in-place if needed; the app will sanitize names for the archive.
+4. **Set date and time** in the [Date & Time Picker](datetime.md). Use the original experiment time.
+5. **[Metadata](metadata.md)** and **[Keywords](keywords.md)**: add search terms and any instrument/sample fields you want to carry into your ELN.
+6. Click **Save ELN archive**, choose a destination folder. If the button is
+   disabled, see [Saving ELN Archives](saving.md) for the required fields.
+7. You now have an ELN archive on disk. Everything above works fully offline; import it later into your ELN (e.g., eLabFTW) once you are back online or transferred the ELN archive to a computer with an internet connection.

docs/user-guide/src/saving.md

@@ -0,0 +1,8 @@
+# Saving ELN Archives
+
+1. Click **Save ELN archive** in the top right corner.
+2. Choose a destination folder for the archive.
+3. Wait for the confirmation message in the bottom status bar.
+
+> [!TIP]
+> If the **Save ELN archive** button is disabled, ensure you have entered a title, date/time and at least a short description. Also make sure all attachments have unique names (no flagged duplicates).