mkdocs-build-plantuml-plugin-ardihikaru


Namemkdocs-build-plantuml-plugin-ardihikaru JSON
Version 1.9.6 PyPI version JSON
download
home_pagehttps://pypi.org/project/mkdocs-build-plantuml-plugin-ardihikaru/1.9.6/#files
SummaryAn MkDocs plugin to call plantuml locally or remote (cloned from: https://github.com/christo-ph/mkdocs_build_plantuml)
upload_time2024-03-08 00:42:43
maintainer
docs_urlNone
authorChristoph Galler
requires_python>=3.2
licenseMIT
keywords mkdocs plantuml publishing documentation uml sequence diagram
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-build-plantuml-plugin)

# MkDocs-Build-Plantuml-Plugin

## Table of Contents

- [About the Project](#about-the-project)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Dark Mode Support](#dark-mode-support)
- [Known restrictions](#known-restrictions)
- [Contributing](#contributing)

## About the Project

This plugin automates the generation of PlantUML image files when using `mkdocs serve`.

The motivation behind this plugin is to provide a solution for users who prefer not to use inline diagrams and have encountered challenges with non-functional !includes.

**Note**: If you want inline diagrams in your Markdown files

````markdown
```plantuml
Alice -> Bob
```
````

this plugin does _not_ meet your requirements. Please check out [plantuml-markdown](https://github.com/mikitex70/plantuml-markdown) which does exactly that.

## Prerequisites

You need to have installed:

- Python3
- [MkDocs](https://www.mkdocs.org)
- Java for Plantuml (If running locally)
- [Plantuml](https://plantuml.com) (if running locally)
- This plugin (needs httplib2 for server rendering)

On macOS you can install plantuml with homebrew which puts a plantuml executable in `/usr/local/bin/plantuml`.

## Installation

```shell
pip3 install mkdocs-build-plantuml-plugin
```

## Usage

### Plugin Settings

In `mkdocs.yml` add this plugin section (depicted are the default values):

```yaml
plugins:
  - search
  - build_plantuml:
      render: 'server' # or "local" for local rendering
      bin_path: '/usr/local/bin/plantuml' # ignored when render: server
      server: 'http://www.plantuml.com/plantuml' # official plantuml server
      disable_ssl_certificate_validation: true # for self-signed and invalid certs
      output_format: 'svg' # or "png"
      allow_multiple_roots: false # in case your codebase contains more locations for diagrams (all ending in diagram_root)
      diagram_root: 'docs/diagrams' # should reside under docs_dir
      output_folder: 'out'
      input_folder: 'src'
      input_extensions: '' # comma separated list of extensions to parse, by default every file is parsed
```

It is recommended to use the `server` option, which is much faster than `local`.

### Example folder structure

This would result in this directory layout:

```python
docs/                         # the default MkDocs docs_dir directory
  diagrams/
    include/                  # for include files like theme.puml etc (optional, won't be generated)
    out/                      # the generated images, which can be included in your md files
      subdir1/file1.svg       # you can organise your diagrams in subfolders, see below
      file.svg
    src/                      # the Plantuml sources
      subdir1/file1.puml
      subdir2/
      file.puml
mkdocs.yml                    # mkdocs configuration file

```

When starting with `mkdocs serve`, it will create all diagrams initially.

Afterwards, it checks if the `*.puml` (or other ending) file has a newer timestamp than the corresponding file in out. If so, it will generate a new image (works also with includes). This way, it won‘t take long until the site reloads and does not get into a loop.

### Including generated images

Inside your `index.md` or any other Markdown file you can then reference any created image as usual:

```markdown
# My MkDocs Document

## Example Plantuml Images

![file](diagrams/out/file.svg)

![file1](diagrams/out/subdir1/file1.svg)
```

## Dark Mode Support

Since Version 1.4 this plugin can support dark mode when rendering with `server` (prefers-color-scheme).

**Note**: Not in local mode, only server rendering mode

1. Grab a general (ie. for [Material Theme](https://squidfunk.github.io/mkdocs-material/)) dark mode support css file (i.e. from [henrywhitaker3/mkdocs-material-dark-theme](https://github.com/henrywhitaker3/mkdocs-material-dark-theme)) for your theme
1. Enable theme support in this plugin:

        - build_plantuml:
            [...]
            theme_enabled: true
            theme_folder: "include/themes"
            theme_light: "light.puml"
            theme_dark: "dark.puml"

1. You have to provide two puml theme files, ie mydarkmode.puml and mylightmode.puml
1. In the out directory a `<file>.<ext>` will be created and additionally a `<file>_dark.<ext>`
1. Insert your images in markdown with `![file](diagrams/out/file.svg#darkable)` (this selector is then used in the [JS file](example/docs/javascript/images_dark.js) to know which images have to be exchanged)
1. provide [`extra_javascript`](./example/docs/javascript/images_dark.js) file which handles the switch

You can find an example in the [example folder](./example/)

### Example Output

![DarkMode](./switch_dark_mode.gif)

## Known restrictions

- If you use `!include` and the `render: "server"` option, this plugin merges those files manually. If there are any issues or side effects because of that, please open a ticket.
- Dark mode / theme support is currently only available in server rendering mode.

## Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.


## Build

            

Raw data

            {
    "_id": null,
    "home_page": "https://pypi.org/project/mkdocs-build-plantuml-plugin-ardihikaru/1.9.6/#files",
    "name": "mkdocs-build-plantuml-plugin-ardihikaru",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.2",
    "maintainer_email": "",
    "keywords": "mkdocs plantuml publishing documentation uml sequence diagram",
    "author": "Christoph Galler",
    "author_email": "galler@quantor.consulting",
    "download_url": "https://files.pythonhosted.org/packages/4d/25/7b046d7b603d5199fff108ba4e054d64840ee2d758b8b3380469fcbefc6e/mkdocs-build-plantuml-plugin-ardihikaru-1.9.6.tar.gz",
    "platform": null,
    "description": "![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-build-plantuml-plugin)\n\n# MkDocs-Build-Plantuml-Plugin\n\n## Table of Contents\n\n- [About the Project](#about-the-project)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Usage](#usage)\n- [Dark Mode Support](#dark-mode-support)\n- [Known restrictions](#known-restrictions)\n- [Contributing](#contributing)\n\n## About the Project\n\nThis plugin automates the generation of PlantUML image files when using `mkdocs serve`.\n\nThe motivation behind this plugin is to provide a solution for users who prefer not to use inline diagrams and have encountered challenges with non-functional !includes.\n\n**Note**: If you want inline diagrams in your Markdown files\n\n````markdown\n```plantuml\nAlice -> Bob\n```\n````\n\nthis plugin does _not_ meet your requirements. Please check out [plantuml-markdown](https://github.com/mikitex70/plantuml-markdown) which does exactly that.\n\n## Prerequisites\n\nYou need to have installed:\n\n- Python3\n- [MkDocs](https://www.mkdocs.org)\n- Java for Plantuml (If running locally)\n- [Plantuml](https://plantuml.com) (if running locally)\n- This plugin (needs httplib2 for server rendering)\n\nOn macOS you can install plantuml with homebrew which puts a plantuml executable in `/usr/local/bin/plantuml`.\n\n## Installation\n\n```shell\npip3 install mkdocs-build-plantuml-plugin\n```\n\n## Usage\n\n### Plugin Settings\n\nIn `mkdocs.yml` add this plugin section (depicted are the default values):\n\n```yaml\nplugins:\n  - search\n  - build_plantuml:\n      render: 'server' # or \"local\" for local rendering\n      bin_path: '/usr/local/bin/plantuml' # ignored when render: server\n      server: 'http://www.plantuml.com/plantuml' # official plantuml server\n      disable_ssl_certificate_validation: true # for self-signed and invalid certs\n      output_format: 'svg' # or \"png\"\n      allow_multiple_roots: false # in case your codebase contains more locations for diagrams (all ending in diagram_root)\n      diagram_root: 'docs/diagrams' # should reside under docs_dir\n      output_folder: 'out'\n      input_folder: 'src'\n      input_extensions: '' # comma separated list of extensions to parse, by default every file is parsed\n```\n\nIt is recommended to use the `server` option, which is much faster than `local`.\n\n### Example folder structure\n\nThis would result in this directory layout:\n\n```python\ndocs/                         # the default MkDocs docs_dir directory\n  diagrams/\n    include/                  # for include files like theme.puml etc (optional, won't be generated)\n    out/                      # the generated images, which can be included in your md files\n      subdir1/file1.svg       # you can organise your diagrams in subfolders, see below\n      file.svg\n    src/                      # the Plantuml sources\n      subdir1/file1.puml\n      subdir2/\n      file.puml\nmkdocs.yml                    # mkdocs configuration file\n\n```\n\nWhen starting with `mkdocs serve`, it will create all diagrams initially.\n\nAfterwards, it checks if the `*.puml` (or other ending) file has a newer timestamp than the corresponding file in out. If so, it will generate a new image (works also with includes). This way, it won\u2018t take long until the site reloads and does not get into a loop.\n\n### Including generated images\n\nInside your `index.md` or any other Markdown file you can then reference any created image as usual:\n\n```markdown\n# My MkDocs Document\n\n## Example Plantuml Images\n\n![file](diagrams/out/file.svg)\n\n![file1](diagrams/out/subdir1/file1.svg)\n```\n\n## Dark Mode Support\n\nSince Version 1.4 this plugin can support dark mode when rendering with `server` (prefers-color-scheme).\n\n**Note**: Not in local mode, only server rendering mode\n\n1. Grab a general (ie. for [Material Theme](https://squidfunk.github.io/mkdocs-material/)) dark mode support css file (i.e. from [henrywhitaker3/mkdocs-material-dark-theme](https://github.com/henrywhitaker3/mkdocs-material-dark-theme)) for your theme\n1. Enable theme support in this plugin:\n\n        - build_plantuml:\n            [...]\n            theme_enabled: true\n            theme_folder: \"include/themes\"\n            theme_light: \"light.puml\"\n            theme_dark: \"dark.puml\"\n\n1. You have to provide two puml theme files, ie mydarkmode.puml and mylightmode.puml\n1. In the out directory a `<file>.<ext>` will be created and additionally a `<file>_dark.<ext>`\n1. Insert your images in markdown with `![file](diagrams/out/file.svg#darkable)` (this selector is then used in the [JS file](example/docs/javascript/images_dark.js) to know which images have to be exchanged)\n1. provide [`extra_javascript`](./example/docs/javascript/images_dark.js) file which handles the switch\n\nYou can find an example in the [example folder](./example/)\n\n### Example Output\n\n![DarkMode](./switch_dark_mode.gif)\n\n## Known restrictions\n\n- If you use `!include` and the `render: \"server\"` option, this plugin merges those files manually. If there are any issues or side effects because of that, please open a ticket.\n- Dark mode / theme support is currently only available in server rendering mode.\n\n## Contributing\n\nContributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.\n\n\n## Build\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "An MkDocs plugin to call plantuml locally or remote (cloned from: https://github.com/christo-ph/mkdocs_build_plantuml)",
    "version": "1.9.6",
    "project_urls": {
        "Homepage": "https://pypi.org/project/mkdocs-build-plantuml-plugin-ardihikaru/1.9.6/#files"
    },
    "split_keywords": [
        "mkdocs",
        "plantuml",
        "publishing",
        "documentation",
        "uml",
        "sequence",
        "diagram"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "69223e34e142a5771d89cdd10d704b361ddedc832291dbbe9e1ee595531813a7",
                "md5": "34ead30ff4d38e2a20288602e543ca20",
                "sha256": "48e3f15c2fbb1ffb89b71753305a4743811880dea14198e0b6899344feaa773f"
            },
            "downloads": -1,
            "filename": "mkdocs_build_plantuml_plugin_ardihikaru-1.9.6-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "34ead30ff4d38e2a20288602e543ca20",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.2",
            "size": 9460,
            "upload_time": "2024-03-08T00:42:41",
            "upload_time_iso_8601": "2024-03-08T00:42:41.772228Z",
            "url": "https://files.pythonhosted.org/packages/69/22/3e34e142a5771d89cdd10d704b361ddedc832291dbbe9e1ee595531813a7/mkdocs_build_plantuml_plugin_ardihikaru-1.9.6-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "4d257b046d7b603d5199fff108ba4e054d64840ee2d758b8b3380469fcbefc6e",
                "md5": "f0b8b44e592474f54163f6d763a8e88e",
                "sha256": "dac2e093450896b67c15ac64665d676b05588776e74ac0255d9d7c98ba05d00e"
            },
            "downloads": -1,
            "filename": "mkdocs-build-plantuml-plugin-ardihikaru-1.9.6.tar.gz",
            "has_sig": false,
            "md5_digest": "f0b8b44e592474f54163f6d763a8e88e",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.2",
            "size": 10840,
            "upload_time": "2024-03-08T00:42:43",
            "upload_time_iso_8601": "2024-03-08T00:42:43.909107Z",
            "url": "https://files.pythonhosted.org/packages/4d/25/7b046d7b603d5199fff108ba4e054d64840ee2d758b8b3380469fcbefc6e/mkdocs-build-plantuml-plugin-ardihikaru-1.9.6.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-03-08 00:42:43",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "mkdocs-build-plantuml-plugin-ardihikaru"
}
        
Elapsed time: 0.25481s