initial commit

2026-05-26 14:27:01 +02:00
commit ef411fbe23
11 changed files with 427 additions and 0 deletions
@@ -0,0 +1,165 @@
+# Obsidian Import Utility
+
+Import **Markdown** and **PDF** files into an [Obsidian](https://obsidian.md) vault with a single click.
+
+## Features
+
+- **.md files**
+  - Copies contents into a new Obsidian note.
+  - Uses the filename as the note title (prepended as `# Title`).
+
+- **.pdf files**
+  - Converts PDF text into a markdown note.
+  - Extracts embedded images and embeds them in the note.
+  - Creates a **hidden folder** per file (e.g. `.myfile_assets/`) containing:
+    - The original PDF
+    - All extracted images
+  - Links back to the original PDF from the note.
+
+## Installation
+
+1. Install Python 3 (usually already present on Linux).
+2. Install the required dependency:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+   Or directly:
+   ```bash
+   pip install pymupdf
+   ```
+
+3. Tell the script where your Obsidian vault lives. Choose **one** method:
+
+   - **Environment variable** (recommended for Thunar):
+     ```bash
+     export OBSIDIAN_VAULT="$HOME/Obsidian/MyVault"
+     ```
+   - **Command-line flag**:
+     ```bash
+     python main.py --vault ~/Obsidian/MyVault /path/to/file.pdf
+     ```
+   - **Auto-detect**: if you have exactly one folder inside `~/Obsidian`, it will be picked automatically.
+
+## Usage
+
+### From the terminal
+
+```bash
+# Markdown
+python main.py /path/to/notes.md
+
+# PDF
+python main.py /path/to/document.pdf
+
+# With explicit vault
+python main.py --vault ~/Obsidian/Work /path/to/slides.pdf
+```
+
+### With the wrapper script
+
+```bash
+./import-to-obsidian.sh /path/to/file.pdf
+```
+
+Edit `VAULT_PATH=""` inside `import-to-obsidian.sh` if you prefer a hard-coded default.
+
+---
+
+## Thunar Custom Action
+
+To add a right-click menu entry in **Thunar** (Xfce file manager):
+
+### Option A – Using the Thunar GUI
+
+1. Open Thunar.
+2. Go to **Edit → Configure custom actions…**
+3. Click **+** (Add a new custom action).
+4. Fill in the fields:
+
+   | Field | Value |
+   |-------|-------|
+   | **Name** | Import to Obsidian |
+   | **Description** | Import selected file into Obsidian vault |
+   | **Command** | `/usr/bin/python3 /full/path/to/main.py --vault /home/USER/Obsidian/MyVault %F` |
+   | **Icon** | `folder-documents` (or any icon you like) |
+
+5. Switch to the **Appearance Conditions** tab.
+6. Check **Text files** and **Other files** (or just `*.md;*.pdf` if you want to restrict it).
+7. Click **OK**.
+
+> **Tip:** `%F` passes all selected files. If you want the action to appear only for single selections you can use `%f` instead.
+
+### Option B – Editing `uca.xml` directly
+
+Paste the following snippet into `~/.config/Thunar/uca.xml` inside the `<actions>` block (adjust paths):
+
+```xml
+<action>
+    <icon>folder-documents</icon>
+    <name>Import to Obsidian</name>
+    <command>/usr/bin/python3 /home/USER/Code/projects/obsidianUtils/importFileToObsidian/main.py --vault /home/USER/Obsidian/MyVault %F</command>
+    <description>Import selected file(s) into Obsidian vault</description>
+    <patterns>*.md;*.pdf</patterns>
+    <other-files/>
+    <text-files/>
+</action>
+```
+
+Restart Thunar or press `Ctrl+Shift+R` inside a Thunar window to reload custom actions.
+
+---
+
+## Environment Variable in `.bashrc`
+
+If you want the vault path to be available everywhere (including Thunar when launched from your shell), add this to `~/.bashrc` or `~/.profile`:
+
+```bash
+export OBSIDIAN_VAULT="$HOME/Obsidian/MyVault"
+```
+
+> Note: Thunar started from a graphical session (not from a terminal) may not see variables defined in `.bashrc`. In that case, hard-code the `--vault` flag in the custom action command.
+
+---
+
+## File Structure After Import
+
+### Markdown import
+
+```
+MyVault/
+└── notes.md          # imported note with '# notes' as title
+```
+
+### PDF import
+
+```
+MyVault/
+├── document.md
+└── .document_assets/
+    ├── document.pdf
+    ├── page_1_img_1.png
+    ├── page_1_img_2.jpg
+    └── page_2_img_1.png
+```
+
+The generated `document.md` contains:
+- The extracted text per page.
+- Embedded images under an "Extracted Images" section.
+- A link back to the original PDF inside the hidden assets folder.
+
+---
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| `Vault path does not exist` | Double-check `--vault` or `OBSIDIAN_VAULT`. |
+| `PDF handling requires 'pymupdf'` | Run `pip install pymupdf`. |
+| Thunar action does not appear | Make sure the file pattern matches (`*.md;*.pdf`) and restart Thunar (`Ctrl+Shift+R`). |
+| Images are missing in the note | `pymupdf` extracts raw embedded images; vector graphics or scanned pages may not yield separate image files. |
+
+## License
+
+MIT (or choose your own).