A command-line tool for processing Markdown files. Currently, it supports automatically downloading remote images to local storage and updating the image references in Markdown files, as well as translating markdown files using AI models.
- Supports processing individual Markdown files or entire directories (including subdirectories).
- Automatically downloads remote images to a specified local directory.
- Preserves original image filenames (where available).
- Handles duplicate filenames automatically.
- Updates image references in Markdown files using relative paths.
- Provides detailed processing logs.
- Translates markdown files using AI models with support for multiple languages.
use Homebrew to install mdctl. Follow the Homebrew Installation Guide to install Homebrew.
brew tap samzong/tap
brew install samzong/tap/mdctlor use go to install mdctl.
go install github.com/samzong/mdctl@latestProcessing a single file:
mdctl download -f path/to/your/file.mdProcessing an entire directory:
mdctl download -d path/to/your/directorySpecifying an output directory for images:
mdctl download -f path/to/your/file.md -o path/to/imagesDownloads and localizes remote images in Markdown files.
Parameters:
-f, --file: Specifies the Markdown file to process.-d, --dir: Specifies the directory to process (recursively processes all Markdown files).-o, --output: Specifies the directory for saving images (optional).- Default:
imagessubdirectory within the file's directory (file mode). - Default:
imagessubdirectory within the specified directory (directory mode).
- Default:
The translate command allows you to translate markdown files or directories to a specified language using AI models.
- OpenAI API (Current)
- Ollama (Coming Soon)
- Google Gemini (Coming Soon)
- Anthropic Claude (Coming Soon)
- Arabic (العربية)
- Chinese (中文)
- English (English)
- French (Français)
- German (Deutsch)
- Hindi (हिन्दी)
- Italian (Italiano)
- Japanese (日本語)
- Korean (한국어)
- Portuguese (Português)
- Russian (Русский)
- Spanish (Español)
- Thai (ไทย)
- Vietnamese (Tiếng Việt)
Create a configuration file at ~/.config/mdctl/config.json with the following content:
{
"translate_prompt": "Please translate the following markdown content to {TARGET_LANG}, keep the markdown format and front matter unchanged:",
"endpoint": "your-api-endpoint",
"api_key": "your-api-key",
"model": "gpt-3.5-turbo",
"temperature": 0.0,
"top_p": 1.0
}Or use the config command to set up:
# Set API endpoint
mdctl config set -k endpoint -v "your-api-endpoint"
# Set API key
mdctl config set -k api_key -v "your-api-key"
# Set model
mdctl config set -k model -v "gpt-3.5-turbo"# Translate a single file to Chinese
mdctl translate -f README.md -l zh
# Translate a directory to Japanese
mdctl translate -f docs -l ja
# Force translate an already translated file
mdctl translate -f README.md -l ko -F
# Translate to a specific output path
mdctl translate -f docs -l fr -t translated_docs- Supports translating single files or entire directories
- Maintains directory structure when translating directories
- Adds front matter to track translation status
- Supports force translation with
-Fflag - Supports translation between multiple languages
- Shows translation progress with detailed status information
The config command allows you to manage your configuration settings.
# List all configuration settings
mdctl config list
# Get a specific configuration value
mdctl config get -k api_key
mdctl config get -k model
# Set a configuration value
mdctl config set -k api_key -v "your-api-key"
mdctl config set -k model -v "gpt-4"
mdctl config set -k temperature -v "0.8"translate_prompt: The prompt template for translationendpoint: AI model API endpoint URLapi_key: Your API keymodel: The model to use for translationtemperature: Temperature setting for the model (0.0 to 1.0)top_p: Top P setting for the model (0.0 to 1.0)
-fand-dparameters cannot be used together- If no output directory is specified, the tool will automatically create a default
imagesdirectory - Only remote images (http/https) will be processed, local image references will not be modified
- Image filenames will retain their original names, if duplicates occur, a hash of the URL will be added as a suffix
