# Mkdocs Plotly Plugin
[MkDocs](https://www.mkdocs.org/) plugin to create interactive charts from data using the declarative [plotly](https://plotly.com/javascript/)'s json syntax.
Includes supports for [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme features like [instant loading](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=reload#instant-loading) and [dark color themes](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle).
## Installation
Install the plugin using `pip3`:
```shell
pip install mkdocs-plotly-plugin
```
And then add the plugin into `plugins` and the custome fence
```yml
plugins:
- plotly
markdown_extensions:
- pymdownx.superfences:
custom_fences:
- name: plotly
class: mkdocs-plotly
format: !!python/name:mkdocs_plotly_plugin.fences.fence_plotly
```
## Usage
You can insert any valid plotly JSON as a codeblock using:
````
``` plotly
{
"data": [
{
"x": [
"giraffes",
"orangutans",
"monkeys"
],
"y": [
20,
14,
23
],
"type": "bar"
}
]
}
```
````
This is compatiable with `snipplets` as well
````
```plotly
--8<-- "assets/data.json"
```
````
or you can insert any plotly JSON through URLs
````
```plotly
{"file_path": "./assets/data.json"}
```
````
Using `snipplets` will insert the json content into the output HTML file, which is more suitable for smaller datasets. Using `file_path` will fetch the json content once the page is loaded.
Plotly has its own eco-system for creating charts in most statistical languages. You can output the plot as a json file through `fig.to_json()`.
### Options
| Option | Default | Description |
| -------- | ------- | ---------------------------------------------------------------------- |
| lib_path | ` ` | Relative path to local `plotly.js` file, or leave it blank to use CDN. |
| template_default | `plotly_min` | template for plotly charts in light mode |
| template_slate | `plotly_dark_min` | template for plotly charts in dark mode |
| enable_template | True | use template to automatically change theme |
Available Plotly templates are `["plotly_min", "plotly_dark_min", "plotly", "plotly_white", "plotly_dark", "ggplot2", "seaborn", "simple_white", "none"]`. If you want to customize your own template, you can export it as a JSON file and provide its relative path in options.
Raw data
{
"_id": null,
"home_page": "https://github.com/haoda-li/mkdocs-plotly-plugin",
"name": "mkdocs-plotly-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "mkdocs plugin",
"author": "Haoda Li",
"author_email": "haoda_li@berkeley.edu",
"download_url": "https://files.pythonhosted.org/packages/4e/5e/ec563f22aa210fe778d9e99fd97d68e00e75a4c374e8983172ae4be7b551/mkdocs-plotly-plugin-0.1.2.tar.gz",
"platform": null,
"description": "\r\n\r\n# Mkdocs Plotly Plugin\r\n\r\n\r\n\r\n\r\n\r\n[MkDocs](https://www.mkdocs.org/) plugin to create interactive charts from data using the declarative [plotly](https://plotly.com/javascript/)'s json syntax. \r\n\r\nIncludes supports for [mkdocs-material](https://github.com/squidfunk/mkdocs-material) theme features like [instant loading](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=reload#instant-loading) and [dark color themes](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/#color-palette-toggle).\r\n\r\n## Installation\r\n\r\nInstall the plugin using `pip3`:\r\n\r\n```shell\r\npip install mkdocs-plotly-plugin \r\n```\r\n\r\nAnd then add the plugin into `plugins` and the custome fence\r\n\r\n```yml\r\nplugins:\r\n - plotly\r\n\r\nmarkdown_extensions:\r\n - pymdownx.superfences:\r\n custom_fences:\r\n - name: plotly\r\n class: mkdocs-plotly\r\n format: !!python/name:mkdocs_plotly_plugin.fences.fence_plotly\r\n```\r\n\r\n## Usage\r\n\r\nYou can insert any valid plotly JSON as a codeblock using:\r\n````\r\n``` plotly\r\n{\r\n \"data\": [\r\n {\r\n \"x\": [\r\n \"giraffes\",\r\n \"orangutans\",\r\n \"monkeys\"\r\n ],\r\n \"y\": [\r\n 20,\r\n 14,\r\n 23\r\n ],\r\n \"type\": \"bar\"\r\n }\r\n ]\r\n}\r\n```\r\n````\r\n\r\n\r\nThis is compatiable with `snipplets` as well\r\n\r\n````\r\n```plotly\r\n--8<-- \"assets/data.json\"\r\n```\r\n````\r\n\r\n\r\nor you can insert any plotly JSON through URLs\r\n\r\n\r\n````\r\n```plotly\r\n{\"file_path\": \"./assets/data.json\"}\r\n```\r\n````\r\n\r\n\r\nUsing `snipplets` will insert the json content into the output HTML file, which is more suitable for smaller datasets. Using `file_path` will fetch the json content once the page is loaded.\r\n\r\nPlotly has its own eco-system for creating charts in most statistical languages. You can output the plot as a json file through `fig.to_json()`.\r\n\r\n### Options\r\n\r\n| Option | Default | Description |\r\n| -------- | ------- | ---------------------------------------------------------------------- |\r\n| lib_path | ` ` | Relative path to local `plotly.js` file, or leave it blank to use CDN. |\r\n| template_default | `plotly_min` | template for plotly charts in light mode |\r\n| template_slate | `plotly_dark_min` | template for plotly charts in dark mode |\r\n| enable_template | True | use template to automatically change theme |\r\n\r\nAvailable Plotly templates are `[\"plotly_min\", \"plotly_dark_min\", \"plotly\", \"plotly_white\", \"plotly_dark\", \"ggplot2\", \"seaborn\", \"simple_white\", \"none\"]`. If you want to customize your own template, you can export it as a JSON file and provide its relative path in options.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "MkDocs plugin to add plotly charts from plotly's json data",
"version": "0.1.2",
"split_keywords": [
"mkdocs",
"plugin"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e30f32e3bc1f1d92e3c2678f41d7a2572c3cd615a97c7368a67cc55b3fbc5619",
"md5": "a5287ba2e2705da224b417e0a9c14401",
"sha256": "ca25c03d99ecd24f649ab27cac87b3dfc5eef12afdb79c0537d6528d0b01fe9e"
},
"downloads": -1,
"filename": "mkdocs_plotly_plugin-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a5287ba2e2705da224b417e0a9c14401",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 14329,
"upload_time": "2023-01-20T19:03:33",
"upload_time_iso_8601": "2023-01-20T19:03:33.595742Z",
"url": "https://files.pythonhosted.org/packages/e3/0f/32e3bc1f1d92e3c2678f41d7a2572c3cd615a97c7368a67cc55b3fbc5619/mkdocs_plotly_plugin-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e5eec563f22aa210fe778d9e99fd97d68e00e75a4c374e8983172ae4be7b551",
"md5": "7e1a23defd2d1ba24c88b777114f4332",
"sha256": "1b6d5c6aa40278aeed9462d8ec2ec158e89a515ac23dc447f098c71f04d3a0fb"
},
"downloads": -1,
"filename": "mkdocs-plotly-plugin-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7e1a23defd2d1ba24c88b777114f4332",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 10513,
"upload_time": "2023-01-20T19:03:35",
"upload_time_iso_8601": "2023-01-20T19:03:35.568771Z",
"url": "https://files.pythonhosted.org/packages/4e/5e/ec563f22aa210fe778d9e99fd97d68e00e75a4c374e8983172ae4be7b551/mkdocs-plotly-plugin-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-20 19:03:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "haoda-li",
"github_project": "mkdocs-plotly-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-plotly-plugin"
}
JSON
