CoolFace
Apppublic

spaceenter12345/pdf-to-markdown

sourceHugging Faceupdated 11mo agoView on Hugging Face
0likes
App README

PDF → Markdown (pdf-2-md)

A Python/Streamlit application that converts PDF files to Markdown quickly and reliably. Ready to deploy for free on Hugging Face Spaces.

Goals

  • —Upload a PDF and get raw Markdown output.
  • —Simple UX with progress and clear error messages.
  • —Optional: side-by-side preview and inline Markdown editing.

MVP: Main Flow

  1. 1.Upload a PDF (size cap depends on Space hardware, ~10–20MB for free CPU).
  2. 2.Click "Convert".
  3. 3.Show processing/progress.
  4. 4.Return raw Markdown.
  5. 5.Download .md via the download button.

Architecture (Python-only on Hugging Face Spaces)

  • —Streamlit app: upload UI + conversion pipeline inside the app.
  • —Docling: main PDF → Markdown engine, with fallbacks.
  • —No separate backend API; Spaces' CPU is sufficient for a demo.

Recommended Stack

  • —Python 3.10+
  • —Streamlit (UI)
  • —Docling (PDF → Markdown)
  • —Optional: requests (import from URL), zipfile (batch export), python-magic (MIME checks)

Directory Structure

pdf-2-md/
├─ app.py              # Streamlit application
├─ requirements.txt    # Python dependencies (streamlit, docling, ...)
├─ docs/               # Docs (specs, plans)
└─ README.md

Roadmap

  • —Phase 1 (MVP – High priority):
  • —Upload + Convert button (Streamlit file_uploader + button).
  • —Display raw Markdown (textarea/code block).
  • —"Download .md" button.
  • —Status/progress + error handling.
  • —Phase 2 (Improvements – Medium):
  • —Side-by-side preview (st.columns: textarea ↔ st.markdown).
  • —Inline Markdown editing.
  • —Phase 3 (Extensions – Low):
  • —Batch conversion (accept_multiple_files, return ZIP).
  • —Conversion options (checkboxes: keep images/tables...).
  • —Import from URL (download PDF via requests).

Technical Next Steps

  • —Ensure requirements.txt includes all libs (streamlit, docling, pymupdf, pdfminer.six...).
  • —Implement app.py basic UI: uploader, convert button, result display, .md download.
  • —Integrate Docling in app.py: robust PDF → Markdown with clear errors.
  • —Size limits and basic MIME checks; consider timeouts.

Deploy to Hugging Face Spaces

Step 1: Create a new Space

  1. 1.Log in to Hugging Face
  2. 2.Go to Spaces → Create new Space
  3. 3.Fill in:
  4. 4.Space name: pdf-to-markdown (or any name)
  5. 5.License: MIT
  6. 6.SDK: Streamlit (if available) or Docker
  7. 7.Hardware: CPU basic (free)
  8. 8.Visibility: Public

Step 2: Upload code

Option A: Web interface

  1. 1.After creating the Space, go to the Files tab.
  2. 2.Upload:
  3. 3.app.py
  4. 4.requirements.txt
  5. 5.README.md (optional)
  6. 6.packages.txt and .streamlit/config.toml (for Streamlit SDK)
  7. 7.Dockerfile (for Docker SDK)

Option B: Git (recommended)

# Clone your Space locally
git clone https://huggingface.co/spaces/YOUR_USERNAME/SPACE_NAME
cd SPACE_NAME

# Copy files from this project
copy ..\pdf-2-md\app.py .
copy ..\pdf-2-md\requirements.txt .
copy ..\pdf-2-md\README.md .
copy ..\pdf-2-md\.streamlit\config.toml .\.streamlit\config.toml
copy ..\pdf-2-md\packages.txt .
copy ..\pdf-2-md\Dockerfile .

# Commit and push
git add .
git commit -m "Initial commit: PDF to Markdown converter"
git push

Step 3: Verify deployment

  1. 1.The Space builds automatically (2–5 minutes).
  2. 2.Check build logs under Logs.
  3. 3.If successful, the app is live at your Space URL.

Step 4: Optimize for Spaces

  • —File size: Set MAX_FILE_SIZE_MB = 20 in app.py.
  • —Timeouts: Free Spaces have ~60s/request limits.
  • —Memory: Free CPU has ~16GB RAM; fine for most PDFs.

Important Notes

  • —Docling: heavy dependencies (PyTorch, etc.). First build can take time.
  • —Fallback: If Docling fails on Spaces, the app automatically falls back to PyMuPDF.
  • —Performance: Free CPU handles PDFs <50MB; processing varies from ~30s to 2min depending on complexity.

When the SDK (Gradio/Streamlit/Static) isn’t selectable

  • —Some newer UIs may not show Streamlit. In that case, choose Docker and use the provided Dockerfile to run Streamlit.
  • —Docker flow:
  • —Choose SDK: Docker when creating the Space.
  • —Upload Dockerfile, requirements.txt, app.py, README.md (no packages.txt needed; system deps installed via apt in the Dockerfile).
  • —After build, the app runs on port 7860 as defined in the Dockerfile.

Troubleshooting: cannot click the SDK box

  • —Ensure the Space name is valid (letters, numbers, -; no spaces).
  • —Select a license (e.g., MIT) first and fill all required fields.
  • —If creating under an Organization, ensure you have permissions; otherwise SDKs may be locked.
  • —Try a different browser, disable script-blocking extensions, or log out/in.
  • —If you reached the free Space quota, delete an old Space and create a new one.

Notes & Risks

  • —Conversion quality depends on Docling; test with diverse PDFs.
  • —Free CPU resources are limited: enforce file size/processing time caps.
  • —Security: validate file types, avoid RCE, rate-limit if needed.

Run Locally

  • —Install deps: pip install -r requirements.txt
  • —Start server: python -m streamlit run app.py
  • —Open: http://localhost:8501/

Notes:

  • —If Docling isn’t available on Windows, the app automatically falls back to PyMuPDF in Auto (PyMuPDF fallback) mode.
  • —Install Docling (recommended on WSL2/Linux): pip install docling --extra-index-url https://download.pytorch.org/whl/cpu