这是一款现代、用户友好的 Web 应用程序,可将 PDF 文档转换为清晰、格式化的 Markdown 文本。
This project is dual-licensed. Please see the License section for comprehensive details.
PDF3MD is a web application designed for efficient conversion of PDF documents into well-structured Markdown and Microsoft Word (DOCX) formats. It features a React-based frontend and a Python Flask backend, providing a seamless user experience with real-time progress updates.
The easiest and recommended way to run PDF3MD is using the provided Docker quick start script.
This method uses pre-built Docker images from Docker Hub for quick setup. You'll need the docker-compose.yml and docker-start.sh script from the repository.
mkdir pdf3md-app && cd pdf3md-app).docker-compose.yml: Create a file named docker-compose.yml in this directory and paste the following content into it:…* **`docker-start.sh`**: Download the `docker-start.sh` script from the [pdf3md GitHub repository's main branch](https://github.com/murtaza-nasir/pdf3md/blob/main/docker-start.sh) and place it in the same directory.
* Make the script executable: `chmod +x ./docker-start.sh`
* (Optional) For development mode using local source code (which requires cloning the full repository), you would also need `docker-compose.dev.yml` from the repository.Start in Production Mode:
In the directory where you placed docker-compose.yml and docker-start.sh, run:
./docker-start.sh startThis will pull the latest images from Docker Hub and start the application.
http://localhost:3000http://localhost:6201Start in Development Mode (with hot-reloading):
./docker-start.sh devThis uses local source code for development if docker-compose.dev.yml is present and configured for local mounts. Otherwise, it may behave like production mode depending on the script's logic.
http://localhost:5173http://localhost:6201Other Useful Script Commands:
./docker-start.sh stop # Stop all services
./docker-start.sh status # Check running services
./docker-start.sh logs # View logs from services
./docker-start.sh rebuild dev example.com # Rebuild development with custom domain
./docker-start.sh help # Display all available script commandsIf you prefer to use Docker Compose commands directly with the pre-built images without the docker-start.sh script:
Create docker-compose.yml:
mkdir pdf3md && cd pdf3md).docker-compose.yml in this directory and paste the content provided in the section above (under "Using Pre-built Docker Images (Recommended)").Pull and Start Services:
In the directory where you created docker-compose.yml, run:
docker compose pull # Pulls the latest images specified in docker-compose.yml
docker compose up -dAccess Application:
http://localhost:3000, Backend API at http://localhost:6201http://example.com:3000, Backend API at http://example.com:6201Stop Services:
docker compose downThis setup is for developing the application locally, not using pre-built images for development.
git clone https://github.com/murtaza-nasir/pdf3md.git
cd pdf3mddocker-compose.dev.yml file, which is typically configured to build images locally and mount source code.docker compose -f docker-compose.dev.yml up --buildhttp://localhost:5173, Backend API at http://localhost:6201http://192.168.1.100:5173, Backend API at http://192.168.1.100:6201docker compose -f docker-compose.dev.yml downThis method involves running the frontend and backend services directly on your machine without Docker, typically for development or if you prefer not to use Docker.
git clone https://github.com/murtaza-nasir/pdf3md.git
cd pdf3mdpdf3md sub-directory (if you are in the root of the cloned repo): cd pdf3mdpip install -r requirements.txtpython app.py
(The backend will be available at http://localhost:6201)pdf3md sub-directory (if you are in the root of the cloned repo): cd pdf3mdnpm installnpm run dev
(The frontend will be available at http://localhost:5173)The pdf3md sub-directory contains scripts for managing both services:
./start_server.sh: Starts both frontend and backend../stop_server.sh: Stops both services.
(Ensure these scripts are executable: chmod +x ./start_server.sh ./stop_server.sh)6201 by default, configurable in pdf3md/app.py.pdf3md/vite.config.js.FLASK_ENV: development or production.FLASK_DEBUG: 1 for debug mode.TZ: Timezone configuration for the backend container. You can modify this in the Docker Compose files to match your local timezone (e.g., America/New_York).The application is designed with the following network assumptions when using the Docker Compose setup:
3000) and backend (port 6201) are expected to be accessed from the same host machine (e.g., http://localhost:3000 for the frontend, which will then try to reach http://localhost:6201 for the backend).http://:3000), the frontend will attempt to connect to the backend at http://:6201. This requires the host machine's firewall to allow incoming connections on port 6201 from other devices on the LAN.6201. For more complex deployment scenarios (e.g., different domains/subdomains for frontend and backend, or API gateways), further configuration, potentially involving environment variables for the API base URL in the frontend build, would be necessary. The current Docker setup is primarily optimized for local development and straightforward LAN access.If you plan to put PDF3MD behind a reverse proxy (e.g., Nginx, Apache, Caddy, Traefik), you need to ensure that requests to your chosen domain are correctly routed to the frontend and backend services.
The frontend application is designed to detect if it's being accessed via a domain name. If so, it will make API requests to the /api path on that same domain. Your reverse proxy must be configured to route these /api/... requests to the backend service (running on port 6201 by default).
Example Nginx Configuration:
Assuming your reverse proxy listens on http://pdf3md.local/ (or your chosen domain):
/ to the frontend service (running on port 3000 by default)./api/ to the backend service (running on port 6201 by default).Here's a sample Nginx location block for routing the API:
…Key considerations for your reverse proxy setup:
3000) at the root of your domain (e.g., http://pdf3md.local/).http://pdf3md.local/api/.... Your proxy needs to strip /api from the path before forwarding to the backend if the backend doesn't expect /api in its routes (which is the case for PDF3MD by default). The proxy_pass http://:6201/; (with a trailing slash) typically handles this correctly in Nginx.Access-Control-Allow-Origin: *). In most reverse proxy setups where the frontend and API are served under the same domain, CORS issues should not arise. However, if you encounter them, ensure your proxy isn't stripping or altering necessary CORS headers.Adjust the proxy_pass directive to point to the correct address of your backend container as seen by the reverse proxy (e.g., http://localhost:6201 if on the same machine, or http://pdf3md-backend:6201 if using Docker service names in a shared Docker network).
3000, 5173 (for dev), and 6201 are not in use by other applications. Use docker compose down to stop existing PDF3MD containers.start_server.sh or stop_server.sh fail, make them executable: chmod +x pdf3md/start_server.sh pdf3md/stop_server.sh.暂无开放 Issues,或尚未同步最近议题。