# PyMD: Python-Powered Markdown
[](https://pepy.tech/projects/pyexecmd)
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.
## ✨ Features
### 🐍 Core Functionality
- **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
### 📝 Document Creation
- **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
### 🎨 Rich Media Support
- **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
### 🔴 Live Development
- **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
## 🚀 Quick Start
### Installation
**Option 1: Install from PyPI (Recommended)**
```bash
pip install pyexecmd
```
<details>
<summary> Option 2: Install from source </summary>
1. **Clone the repository:**
```bash
git clone https://www.github.com/treeleaves30760/PyMD
cd PyMD
```
2. **Install in development mode:**
```bash
pip install -e .
```
</details>
## Usage
### For PyPI Installation
1. **Create a new PyMD document:**
```bash
pyexecmd create my_document.pymd
```
2. **Start live preview with web editor:**
```bash
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 8000` or another port to avoid conflicts.
3. **Export Options:**
```bash
# Render to HTML
pyexecmd render my_document.pymd -o output.html
# Render to Markdown
pyexecmd render my_document.pymd -f markdown -o output.md
```
<details>
<summary> For Conda Users (Recommended Development Setup) </summary>
If you're using conda for development, first activate the environment:
```bash
# Initialize conda and activate environment
source /opt/miniconda3/etc/profile.d/conda.sh && conda activate PyMD
# Verify activation
python --version && which python
```
Then use standard Python commands:
```bash
# 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.md
```
</details>
### Web Editor Features
The 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
## 📝 PyMD Syntax
Please refer to [Syntex Guide](./PyMD_Syntax_Guide.md) to learn how to write the PyMD
### 🚀 Quick Example Usage
**1. Run as executable Python:**
```bash
python example.pymd
```
**2. Render as beautiful HTML:**
```bash
python -m pymd.cli render example.pymd -o presentation.html
```
**3. Export to standard Markdown:**
```bash
python -m pymd.cli render example.pymd -f markdown -o documentation.md
```
**4. Live editor with preview:**
```bash
python -m pymd.cli serve --file example.pymd --port 8080
# Open http://localhost:8080/editor in your browser
```
**How 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:
```bash
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.mp4
```
**Web Editor Features:**
1. **Live Editing**: Open `http://localhost:8080/editor` in your browser
2. **Syntax Highlighting**: `#` prefixed markdown and Python code blocks
3. **Live Preview**: See rendered output in real-time
4. **Export Options**: Click **📄 Export HTML** or **📝 Export MD**
5. **File Execution**: Use Ctrl+S to execute code and update preview
## 🎯 Use Cases
- **📊 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
## 🤝 Contributing
We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.
## 📄 License
This project is licensed under the MIT License.
---
Raw data
{
"_id": null,
"home_page": null,
"name": "pyexecmd",
"maintainer": "PyExecMD Team",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "markdown, python, documentation, jupyter, notebook",
"author": "PyExecMD Team",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/59/bc/184cefde06bce5144778ea30cc60b424c27fd7d409446727a6ba850b64a7/pyexecmd-0.1.8.tar.gz",
"platform": null,
"description": "# PyMD: Python-Powered Markdown\n\n[](https://pepy.tech/projects/pyexecmd)\n\nPyMD 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.\n\n\n\n## \u2728 Features\n\n### \ud83d\udc0d Core Functionality\n\n- **Executable Python Files**: Run directly with `python filename.pymd`\n- **Dual Code Blocks**: ``` for executable code, ```` for display-only\n- **Variable Persistence**: Variables persist across code blocks\n\n### \ud83d\udcdd Document Creation\n\n- **Commented Markdown**: All markdown prefixed with `#` (Python comments)\n- **Print-to-Markdown**: `print()` statements output markdown during rendering\n- **Dynamic Content**: Execute Python code and display results inline\n\n### \ud83c\udfa8 Rich Media Support\n\n- **Automatic Plot Capture**: `plt.show()` saves and renders matplotlib plots\n- **Video Rendering**: Built-in video support with custom controls\n- **Table Detection**: Automatic markdown table formatting\n\n### \ud83d\udd34 Live Development\n\n- **Real-time Preview**: Auto-refresh as you edit with web editor\n- **One-click Export**: Export to HTML or Markdown with embedded media\n- **Fast Rendering**: Efficient parsing with caching\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n**Option 1: Install from PyPI (Recommended)**\n\n```bash\npip install pyexecmd\n```\n\n<details>\n\n<summary> Option 2: Install from source </summary>\n\n1. **Clone the repository:**\n\n ```bash\n git clone https://www.github.com/treeleaves30760/PyMD\n cd PyMD\n ```\n\n2. **Install in development mode:**\n\n ```bash\n pip install -e .\n ```\n\n</details>\n\n## Usage\n\n### For PyPI Installation\n\n1. **Create a new PyMD document:**\n\n ```bash\n pyexecmd create my_document.pymd\n ```\n\n2. **Start live preview with web editor:**\n\n ```bash\n pyexecmd serve --file my_document.pymd --port 8080\n ```\n\n Then open <http://localhost:8080/editor> in your browser for the full editor experience, or <http://localhost:8080> for display-only view.\n\n > **Note for macOS users:** Port 5000 is often used by AirPlay. Use `--port 8000` or another port to avoid conflicts.\n\n3. **Export Options:**\n\n ```bash\n # Render to HTML\n pyexecmd render my_document.pymd -o output.html\n \n # Render to Markdown\n pyexecmd render my_document.pymd -f markdown -o output.md\n ```\n\n<details>\n<summary> For Conda Users (Recommended Development Setup) </summary>\n\nIf you're using conda for development, first activate the environment:\n\n```bash\n# Initialize conda and activate environment\nsource /opt/miniconda3/etc/profile.d/conda.sh && conda activate PyMD\n\n# Verify activation\npython --version && which python\n```\n\nThen use standard Python commands:\n\n```bash\n# Create a new PyMD document\npython -m pymd.cli create my_document.pymd\n\n# Start live preview with web editor\npython -m pymd.cli serve --file my_document.pymd --port 8080\n\n# Render to HTML\npython -m pymd.cli render my_document.pymd -o output.html\n\n# Render to Markdown\npython -m pymd.cli render my_document.pymd -f markdown -o output.md\n```\n\n</details>\n\n### Web Editor Features\n\nThe web editor (available at `/editor`) includes:\n\n- **\ud83d\udcdd Split-view editing**: Side-by-side editor and live preview\n- **\ud83d\uddb1\ufe0f One-click export**: Export HTML and Markdown buttons in the interface\n- **\u26a1 Live rendering**: Ctrl+S to execute code and update preview\n- **\ud83d\udcbe File management**: Save and download your documents\n- **\ud83c\udfa8 Syntax highlighting**: Python syntax highlighting with PyMD-specific features\n\n## \ud83d\udcdd PyMD Syntax\n\nPlease refer to [Syntex Guide](./PyMD_Syntax_Guide.md) to learn how to write the PyMD\n\n### \ud83d\ude80 Quick Example Usage\n\n**1. Run as executable Python:**\n\n```bash\npython example.pymd\n```\n\n**2. Render as beautiful HTML:**\n\n```bash\npython -m pymd.cli render example.pymd -o presentation.html\n```\n\n**3. Export to standard Markdown:**\n\n```bash\npython -m pymd.cli render example.pymd -f markdown -o documentation.md\n```\n\n**4. Live editor with preview:**\n\n```bash\npython -m pymd.cli serve --file example.pymd --port 8080\n# Open http://localhost:8080/editor in your browser\n```\n\n**How Export Works:**\n\n- **HTML Export**: Full rendering with executed code output and styled markdown\n- **Markdown Export**: Removes `#` prefixes and converts to standard markdown\n- **Source Files**: Remain executable Python scripts with commented markdown\n- **Compatibility**: Exported markdown works with GitHub, GitLab, and other renderers\n\n**Output Directory Structure:**\n\nAfter rendering documents with images and videos, your output directory will look like:\n\n```bash\nmy_project/\n\u251c\u2500\u2500 document.pymd # Source PyMD file\n\u251c\u2500\u2500 document.html # Rendered HTML output\n\u251c\u2500\u2500 images/ # Auto-generated plot images\n\u2502 \u251c\u2500\u2500 plot_1_abc123.png\n\u2502 \u2514\u2500\u2500 plot_2_def456.png\n\u2514\u2500\u2500 videos/ # Embedded video files\n \u251c\u2500\u2500 video_1_ghi789.mp4\n \u2514\u2500\u2500 video_2_jkl012.mp4\n```\n\n**Web Editor Features:**\n\n1. **Live Editing**: Open `http://localhost:8080/editor` in your browser\n2. **Syntax Highlighting**: `#` prefixed markdown and Python code blocks\n3. **Live Preview**: See rendered output in real-time\n4. **Export Options**: Click **\ud83d\udcc4 Export HTML** or **\ud83d\udcdd Export MD**\n5. **File Execution**: Use Ctrl+S to execute code and update preview\n\n## \ud83c\udfaf Use Cases\n\n- **\ud83d\udcca Data Science Reports**: Python scripts that execute analysis AND generate beautiful reports with automatic plot capture\n- **\ud83d\udcda Executable Documentation**: Documentation that actually runs and validates itself, with embedded visualizations and demo videos\n- **\ud83c\udf93 Interactive Tutorials**: Learning materials that students can execute and modify, featuring live charts, tables, and instructional videos\n- **\ud83d\udcc8 Living Dashboards**: Python scripts that generate dynamic visual reports with automatic image saving\n- **\ud83d\udd2c Reproducible Research**: Research papers where the code actually runs and produces publication-ready figures\n- **\ud83e\uddea Literate Programming**: Self-documenting code through executable markdown comments with inline visualizations\n- **\ud83d\udccb Technical Specifications**: Specs that include working code examples and automatically generated plots\n- **\ud83e\udd16 AI/ML Workflows**: Machine learning pipelines with embedded documentation and automatic model visualization\n- **\ud83d\udcd1 Business Reports**: Automated reports with data tables and charts that update when code runs\n- **\ud83c\udfa8 Presentation Materials**: Technical presentations that combine code, explanation, live visualizations, and demo videos\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please feel free to submit issues, feature requests, or pull requests.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License.\n\n---\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python-Powered Markdown with executable code and dynamic content",
"version": "0.1.8",
"project_urls": {
"Bug Reports": "https://github.com/treeleaves30760/PyMD/issues",
"Homepage": "https://github.com/treeleaves30760/PyMD",
"Source": "https://github.com/treeleaves30760/PyMD"
},
"split_keywords": [
"markdown",
" python",
" documentation",
" jupyter",
" notebook"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "214924137a2824f6dea54c0a59458a092ccff2ae80a9a6591a0afabaffd93241",
"md5": "0f5ec37fb787a5b50981f98115c646e1",
"sha256": "f882b623bb52725cf4e1eaeda200b1b220a02dc5f92cab3f62244444798f160d"
},
"downloads": -1,
"filename": "pyexecmd-0.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f5ec37fb787a5b50981f98115c646e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 43454,
"upload_time": "2025-08-30T06:37:01",
"upload_time_iso_8601": "2025-08-30T06:37:01.716660Z",
"url": "https://files.pythonhosted.org/packages/21/49/24137a2824f6dea54c0a59458a092ccff2ae80a9a6591a0afabaffd93241/pyexecmd-0.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "59bc184cefde06bce5144778ea30cc60b424c27fd7d409446727a6ba850b64a7",
"md5": "f6f2fa43c75b077c58d464e87bf4460d",
"sha256": "b848a1954396e5b84807537be2079da6852308e59b31895e02e2fc75307298f8"
},
"downloads": -1,
"filename": "pyexecmd-0.1.8.tar.gz",
"has_sig": false,
"md5_digest": "f6f2fa43c75b077c58d464e87bf4460d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 47122,
"upload_time": "2025-08-30T06:37:03",
"upload_time_iso_8601": "2025-08-30T06:37:03.085910Z",
"url": "https://files.pythonhosted.org/packages/59/bc/184cefde06bce5144778ea30cc60b424c27fd7d409446727a6ba850b64a7/pyexecmd-0.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 06:37:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "treeleaves30760",
"github_project": "PyMD",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "Flask",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.3.0"
]
]
},
{
"name": "Flask-SocketIO",
"specs": [
[
"<",
"6.0.0"
],
[
">=",
"5.3.0"
]
]
},
{
"name": "matplotlib",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"2.1.0"
]
]
},
{
"name": "numpy",
"specs": [
[
"<",
"2.0.0"
],
[
">=",
"1.24.0"
]
]
},
{
"name": "watchdog",
"specs": [
[
">=",
"3.0.0"
]
]
},
{
"name": "python-socketio",
"specs": [
[
">=",
"5.8.0"
]
]
},
{
"name": "Werkzeug",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"2.3.0"
]
]
},
{
"name": "tabulate",
"specs": [
[
">=",
"0.9.0"
]
]
}
],
"lcname": "pyexecmd"
}
JSON
