obsidian_utils/importFileToObsidian/README.md

Obsidian Import Utility

Import Markdown and PDF files into an Obsidian 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:

   pip install -r requirements.txt
   

   Or directly:

   pip install pymupdf
   

3. Tell the script where your Obsidian vault lives. Choose one method:

   • Environment variable (recommended for Thunar):

     export OBSIDIAN_VAULT="$HOME/Obsidian/MyVault"
     

   • Command-line flag:

     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

# 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

./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):

<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:

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).