# MkDocs Markdown Preview Plugin
A MkDocs plugin that renders markdown code blocks with md preview syntax into side-by-side boxes, showing both the original source code and the rendered output.
## Features
- **Side-by-side preview**: Shows markdown source and rendered output simultaneously
- **Customizable headers**: Configure titles for source and rendered sections
- **Responsive design**: Automatically adapts to mobile devices
- **Easy integration**: Simple setup with existing MkDocs projects
- **Horizontal scrolling**: Handles wide content without truncation
- **Nested code blocks**: Properly handles code blocks within preview blocks
## Installation
Install the plugin using pip:
```bash
pip install mkdocs-md-preview
```
## Usage
### 1. Add to MkDocs configuration
Add the plugin to your mkdocs.yml file:
```yaml
plugins:
- md-preview
```
### 2. Configure (optional)
You can customize the plugin with these options:
```yaml
plugins:
- md-preview:
enable: true
left_title: "Markdown Source"
right_title: "Rendered Output"
```
### 3. Add CSS (recommended)
Add the CSS styles to your extra.css file:
```css
/* Markdown Preview Plugin Styles */
.markdown-preview-container {
margin: 1.5em 0;
border: 1px solid var(--md-default-fg-color--lighter);
border-radius: 0.2rem;
background-color: var(--md-code-bg-color);
overflow: hidden;
}
.markdown-preview-wrapper {
display: flex;
min-height: 200px;
overflow-x: auto;
min-width: 100%;
}
.markdown-preview-left,
.markdown-preview-right {
flex: 1;
min-width: 300px;
max-width: 50%;
display: flex;
flex-direction: column;
white-space: nowrap;
}
.markdown-preview-left {
border-right: 1px solid var(--md-default-fg-color--lighter);
}
.markdown-preview-header {
background-color: var(--md-default-fg-color--lightest);
padding: 0.5rem 1rem;
font-weight: 600;
font-size: 0.9rem;
border-bottom: 1px solid var(--md-default-fg-color--lighter);
color: var(--md-default-fg-color--light);
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.markdown-preview-content {
flex: 1;
padding: 1rem;
overflow: auto;
white-space: nowrap;
}
.markdown-preview-left .markdown-preview-content {
background-color: var(--md-code-bg-color);
}
.markdown-preview-left .markdown-preview-content pre {
margin: 0;
background-color: transparent;
border: none;
padding: 0;
white-space: pre;
overflow-x: auto;
overflow-y: auto;
}
.markdown-preview-left .markdown-preview-content code {
background-color: transparent;
padding: 0;
font-size: 0.85em;
line-height: 1.4;
white-space: pre;
display: block;
overflow-x: auto;
}
.markdown-preview-right .markdown-preview-content {
background-color: var(--md-default-bg-color);
white-space: normal;
}
.markdown-preview-rendered {
min-width: 100%;
overflow-x: auto;
}
.markdown-preview-rendered > *:first-child {
margin-top: 0 !important;
}
.markdown-preview-rendered > *:last-child {
margin-bottom: 0 !important;
}
.markdown-preview-rendered table {
min-width: 100%;
white-space: nowrap;
}
.markdown-preview-rendered pre {
overflow-x: auto;
white-space: pre;
}
.markdown-preview-rendered code {
white-space: pre;
}
/* Responsive design */
@media screen and (max-width: 768px) {
.markdown-preview-wrapper {
flex-direction: column;
overflow-x: visible;
}
.markdown-preview-left,
.markdown-preview-right {
max-width: none;
min-width: 100%;
}
.markdown-preview-left {
border-right: none;
border-bottom: 1px solid var(--md-default-fg-color--lighter);
}
.markdown-preview-content {
overflow-x: auto;
white-space: nowrap;
}
.markdown-preview-right .markdown-preview-content {
white-space: normal;
}
}
```
### 4. Use in your markdown files
Use the md preview syntax in your markdown files:
```markdown
```md preview
# Example Heading
This is **bold text** and this is *italic text*.
- List item 1
- List item 2
- List item 3
```python
def hello_world():
print("Hello, World!")
\```
This will render as a side-by-side view showing both the markdown source and the rendered HTML output.
## Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| enable | bool | rue | Enable or disable the plugin |
| left_title | string | "Markdown Source" | Title for the source code panel |
|
ight_title | string | "Rendered Output" | Title for the rendered output panel |
```
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/mkdocs-md-preview",
"name": "mkdocs-md-preview",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mkdocs, plugin, markdown, preview, side-by-side",
"author": "Your Name",
"author_email": "Paul Liu <20290410+Paulkm2006@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/06/41/72297213db40853bd4d9f73e827c26cdc152c21fa9db3dc5484da3acb5ad/mkdocs_md_preview-1.0.0.tar.gz",
"platform": null,
"description": "\ufeff# MkDocs Markdown Preview Plugin\n\nA MkDocs plugin that renders markdown code blocks with md preview syntax into side-by-side boxes, showing both the original source code and the rendered output.\n\n## Features\n\n- **Side-by-side preview**: Shows markdown source and rendered output simultaneously\n- **Customizable headers**: Configure titles for source and rendered sections\n- **Responsive design**: Automatically adapts to mobile devices\n- **Easy integration**: Simple setup with existing MkDocs projects\n- **Horizontal scrolling**: Handles wide content without truncation\n- **Nested code blocks**: Properly handles code blocks within preview blocks\n\n## Installation\n\nInstall the plugin using pip:\n\n```bash\npip install mkdocs-md-preview\n```\n\n## Usage\n\n### 1. Add to MkDocs configuration\n\nAdd the plugin to your mkdocs.yml file:\n\n```yaml\nplugins:\n - md-preview\n```\n\n### 2. Configure (optional)\n\nYou can customize the plugin with these options:\n\n```yaml\nplugins:\n - md-preview:\n enable: true\n left_title: \"Markdown Source\"\n right_title: \"Rendered Output\"\n```\n\n### 3. Add CSS (recommended)\n\nAdd the CSS styles to your extra.css file:\n\n```css\n/* Markdown Preview Plugin Styles */\n.markdown-preview-container {\n margin: 1.5em 0;\n border: 1px solid var(--md-default-fg-color--lighter);\n border-radius: 0.2rem;\n background-color: var(--md-code-bg-color);\n overflow: hidden;\n}\n\n.markdown-preview-wrapper {\n display: flex;\n min-height: 200px;\n overflow-x: auto;\n min-width: 100%;\n}\n\n.markdown-preview-left,\n.markdown-preview-right {\n flex: 1;\n min-width: 300px;\n max-width: 50%;\n display: flex;\n flex-direction: column;\n white-space: nowrap;\n}\n\n.markdown-preview-left {\n border-right: 1px solid var(--md-default-fg-color--lighter);\n}\n\n.markdown-preview-header {\n background-color: var(--md-default-fg-color--lightest);\n padding: 0.5rem 1rem;\n font-weight: 600;\n font-size: 0.9rem;\n border-bottom: 1px solid var(--md-default-fg-color--lighter);\n color: var(--md-default-fg-color--light);\n white-space: nowrap;\n overflow: hidden;\n text-overflow: ellipsis;\n}\n\n.markdown-preview-content {\n flex: 1;\n padding: 1rem;\n overflow: auto;\n white-space: nowrap;\n}\n\n.markdown-preview-left .markdown-preview-content {\n background-color: var(--md-code-bg-color);\n}\n\n.markdown-preview-left .markdown-preview-content pre {\n margin: 0;\n background-color: transparent;\n border: none;\n padding: 0;\n white-space: pre;\n overflow-x: auto;\n overflow-y: auto;\n}\n\n.markdown-preview-left .markdown-preview-content code {\n background-color: transparent;\n padding: 0;\n font-size: 0.85em;\n line-height: 1.4;\n white-space: pre;\n display: block;\n overflow-x: auto;\n}\n\n.markdown-preview-right .markdown-preview-content {\n background-color: var(--md-default-bg-color);\n white-space: normal;\n}\n\n.markdown-preview-rendered {\n min-width: 100%;\n overflow-x: auto;\n}\n\n.markdown-preview-rendered > *:first-child {\n margin-top: 0 !important;\n}\n\n.markdown-preview-rendered > *:last-child {\n margin-bottom: 0 !important;\n}\n\n.markdown-preview-rendered table {\n min-width: 100%;\n white-space: nowrap;\n}\n\n.markdown-preview-rendered pre {\n overflow-x: auto;\n white-space: pre;\n}\n\n.markdown-preview-rendered code {\n white-space: pre;\n}\n\n/* Responsive design */\n@media screen and (max-width: 768px) {\n .markdown-preview-wrapper {\n flex-direction: column;\n overflow-x: visible;\n }\n \n .markdown-preview-left,\n .markdown-preview-right {\n max-width: none;\n min-width: 100%;\n }\n \n .markdown-preview-left {\n border-right: none;\n border-bottom: 1px solid var(--md-default-fg-color--lighter);\n }\n \n .markdown-preview-content {\n overflow-x: auto;\n white-space: nowrap;\n }\n \n .markdown-preview-right .markdown-preview-content {\n white-space: normal;\n }\n}\n```\n\n### 4. Use in your markdown files\n\nUse the md preview syntax in your markdown files:\n\n```markdown\n```md preview\n# Example Heading\n\nThis is **bold text** and this is *italic text*.\n\n- List item 1\n- List item 2\n- List item 3\n\n```python\ndef hello_world():\n print(\"Hello, World!\")\n\n\\```\n\nThis will render as a side-by-side view showing both the markdown source and the rendered HTML output.\n\n## Configuration Options\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| enable | bool | \true | Enable or disable the plugin |\n| left_title | string | \"Markdown Source\" | Title for the source code panel |\n| \night_title | string | \"Rendered Output\" | Title for the rendered output panel |\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin for side-by-side markdown preview",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/Paulkm2006/mkdocs-md-preview"
},
"split_keywords": [
"mkdocs",
" plugin",
" markdown",
" preview",
" side-by-side"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b42e6f623ef895c0324999041a2732b4ea4859add924ad80bf966b19c2e9502d",
"md5": "92aa25101af6fef7c5349f81903d1a7e",
"sha256": "15c9ebf492afa1862a88406ba9853f8b3f9594d9c275c52db5441e2b3fe98ec4"
},
"downloads": -1,
"filename": "mkdocs_md_preview-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "92aa25101af6fef7c5349f81903d1a7e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 6397,
"upload_time": "2025-08-24T03:11:55",
"upload_time_iso_8601": "2025-08-24T03:11:55.316486Z",
"url": "https://files.pythonhosted.org/packages/b4/2e/6f623ef895c0324999041a2732b4ea4859add924ad80bf966b19c2e9502d/mkdocs_md_preview-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "064172297213db40853bd4d9f73e827c26cdc152c21fa9db3dc5484da3acb5ad",
"md5": "6e3ced987452cbac46a69e0dc53de64e",
"sha256": "4a3097a1cc6ae762fbae1468974d0cc5460ef8197d5c33a574255ac4d5b50abf"
},
"downloads": -1,
"filename": "mkdocs_md_preview-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "6e3ced987452cbac46a69e0dc53de64e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6086,
"upload_time": "2025-08-24T03:11:56",
"upload_time_iso_8601": "2025-08-24T03:11:56.614013Z",
"url": "https://files.pythonhosted.org/packages/06/41/72297213db40853bd4d9f73e827c26cdc152c21fa9db3dc5484da3acb5ad/mkdocs_md_preview-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 03:11:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "mkdocs-md-preview",
"github_not_found": true,
"lcname": "mkdocs-md-preview"
}
JSON
