How luler/file2markdown works
Project type and purpose
• This is a small, containerized Python micro-service that exposes a REST API to convert uploaded office documents to Markdown.
• The README calls it “文件转markdown” – a file-to-markdown API.
File structure
• Top-level files only:
• main.py – the application entrypoint
• requirements.txt – Python dependencies
• Dockerfile & docker-compose.yml – container build and orchestration
• .dockerignore, .gitignore, CI workflow under .github – standard dev ops support
• No “frontend” or “database” directories, so this is purely a backend conversion service.
README for additional insights
• Runtime dependencies: LibreOffice (headless) + Pandoc (must be installed in the host or container)
• Exposes one endpoint: POST /convert on port 6677
• Two launch options: run in a local Python environment or via Docker Compose
a. Main components
• External client(s) (e.g., curl, Postman, another service)
• API Service container
• Flask or FastAPI application (main.py)
• Conversion module calling LibreOffice & Pandoc binaries
• Underlying conversion engines
• LibreOffice headless (for doc→docx→…)
• Pandoc (for docx→markdown)
• Infrastructure layer
• Docker Engine
• docker-compose orchestrator
b. Relationships & interactions
• Client → HTTP over port 6677 → API Service
• API Service → spawn or shell-out to LibreOffice → produce intermediate file
• API Service → invoke Pandoc → produce Markdown stream
• API Service → return Markdown response to client
c. Architectural patterns & design principles
• Single-responsibility microservice
• Container-first design with Dockerfile & Compose for easy setup
• Dependency isolation: Python libs separated from native binaries (LibreOffice, Pandoc)
d. Key technologies
• Python + web framework (Flask/FastAPI)
• LibreOffice, Pandoc (native CLI tools)
• Docker / Docker Compose
• pip + requirements.txt
Final advice
• Be detailed: include the exact port (6677), note the requirement for LibreOffice+Pandoc installation, and call out Docker Compose’s role.