166 lines
4.5 KiB
Markdown
166 lines
4.5 KiB
Markdown
# 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).
|