PyMD is a revolutionary markup language that creates executable Python files that also render beautifully as markdown documents. All markdown content is prefixed with # (making it Python comments), while code blocks contain regular executable Python code that prints markdown during rendering.
- Executable Python Files: Run directly with
python filename.pymd - Dual Code Blocks: ``` for executable code, ```` for display-only
- Variable Persistence: Variables persist across code blocks
- Commented Markdown: All markdown prefixed with
#(Python comments) - Print-to-Markdown:
print()statements output markdown during rendering - Dynamic Content: Execute Python code and display results inline
- Automatic Plot Capture:
plt.show()saves and renders matplotlib plots - Video Rendering: Built-in video support with custom controls
- Table Detection: Automatic markdown table formatting
- Real-time Preview: Auto-refresh as you edit with web editor
- One-click Export: Export to HTML or Markdown with embedded media
- Fast Rendering: Efficient parsing with caching
Option 1: Install from PyPI (Recommended)
pip install pyexecmdOption 2: Install from source
-
Clone the repository:
git clone https://www.github.com/treeleaves30760/PyMD cd PyMD -
Install in development mode:
pip install -e .
-
Create a new PyMD document:
pyexecmd create my_document.pymd
-
Start live preview with web editor:
pyexecmd serve --file my_document.pymd --port 8080
Then open http://localhost:8080/editor in your browser for the full editor experience, or http://localhost:8080 for display-only view.
Note for macOS users: Port 5000 is often used by AirPlay. Use
--port 8000or another port to avoid conflicts. -
Export Options:
# Render to HTML pyexecmd render my_document.pymd -o output.html # Render to Markdown pyexecmd render my_document.pymd -f markdown -o output.md
For Conda Users (Recommended Development Setup)
If you're using conda for development, first activate the environment:
# Initialize conda and activate environment
source /opt/miniconda3/etc/profile.d/conda.sh && conda activate PyMD
# Verify activation
python --version && which pythonThen use standard Python commands:
# Create a new PyMD document
python -m pymd.cli create my_document.pymd
# Start live preview with web editor
python -m pymd.cli serve --file my_document.pymd --port 8080
# Render to HTML
python -m pymd.cli render my_document.pymd -o output.html
# Render to Markdown
python -m pymd.cli render my_document.pymd -f markdown -o output.mdThe web editor (available at /editor) includes:
- 📝 Split-view editing: Side-by-side editor and live preview
- 🖱️ One-click export: Export HTML and Markdown buttons in the interface
- ⚡ Live rendering: Ctrl+S to execute code and update preview
- 💾 File management: Save and download your documents
- 🎨 Syntax highlighting: Python syntax highlighting with PyMD-specific features
Please refer to Syntex Guide to learn how to write the PyMD
1. Run as executable Python:
python example.pymd2. Render as beautiful HTML:
python -m pymd.cli render example.pymd -o presentation.html3. Export to standard Markdown:
python -m pymd.cli render example.pymd -f markdown -o documentation.md4. Live editor with preview:
python -m pymd.cli serve --file example.pymd --port 8080
# Open http://localhost:8080/editor in your browserHow Export Works:
- HTML Export: Full rendering with executed code output and styled markdown
- Markdown Export: Removes
#prefixes and converts to standard markdown - Source Files: Remain executable Python scripts with commented markdown
- Compatibility: Exported markdown works with GitHub, GitLab, and other renderers
Output Directory Structure:
After rendering documents with images and videos, your output directory will look like:
my_project/
├── document.pymd # Source PyMD file
├── document.html # Rendered HTML output
├── images/ # Auto-generated plot images
│ ├── plot_1_abc123.png
│ └── plot_2_def456.png
└── videos/ # Embedded video files
├── video_1_ghi789.mp4
└── video_2_jkl012.mp4Web Editor Features:
- Live Editing: Open
http://localhost:8080/editorin your browser - Syntax Highlighting:
#prefixed markdown and Python code blocks - Live Preview: See rendered output in real-time
- Export Options: Click 📄 Export HTML or 📝 Export MD
- File Execution: Use Ctrl+S to execute code and update preview
- 📊 Data Science Reports: Python scripts that execute analysis AND generate beautiful reports with automatic plot capture
- 📚 Executable Documentation: Documentation that actually runs and validates itself, with embedded visualizations and demo videos
- 🎓 Interactive Tutorials: Learning materials that students can execute and modify, featuring live charts, tables, and instructional videos
- 📈 Living Dashboards: Python scripts that generate dynamic visual reports with automatic image saving
- 🔬 Reproducible Research: Research papers where the code actually runs and produces publication-ready figures
- 🧪 Literate Programming: Self-documenting code through executable markdown comments with inline visualizations
- 📋 Technical Specifications: Specs that include working code examples and automatically generated plots
- 🤖 AI/ML Workflows: Machine learning pipelines with embedded documentation and automatic model visualization
- 📑 Business Reports: Automated reports with data tables and charts that update when code runs
- 🎨 Presentation Materials: Technical presentations that combine code, explanation, live visualizations, and demo videos
.pymd files.
- Only run
.pymdfiles from trusted sources - Review code before executing downloaded
.pymdfiles - Don't expose the PyMD server to public networks without authentication
- See SECURITY.md for detailed security guidelines
We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.
This project is licensed under the MIT License.