docs: convert examples into actual mkdocs github page (#27)

* docs: convert examples into actual mkdocs github page

Co-Authored-By: Yves Chevallier <yves.chevallier@heig-vd.ch>
Signed-off-by: Jan Larwig <jan@larwig.com>

* build: add docs workflow

---------

Signed-off-by: Jan Larwig <jan@larwig.com>
Co-authored-by: Yves Chevallier <yves.chevallier@heig-vd.ch>

Author: tuunit

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: ci
+on:
+  push:
+    branches:
+      - main
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - name: Install mkdocs-drawio
+        run: |
+          pip install poetry
+          poetry build
+      - name: Build and publish docs
+        run: |
+          cd examples
+          pip install -r requirements.txt
+          mkdocs gh-deploy --force

.gitignore

@@ -158,3 +158,10 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
+
+# Backups generated from the Desktop application
+*.drawio.bkp
+
+
+# Temporary files generated by Windows on WSL
+*:Zone.Identifier

README.md

@@ -2,10 +2,9 @@
 [![Publish Badge](https://github.com/tuunit/mkdocs-drawio/workflows/Publish/badge.svg)](https://github.com/tuunit/mkdocs-drawio/actions)
 [![PyPI](https://img.shields.io/pypi/v/mkdocs-drawio)](https://pypi.org/project/mkdocs-drawio/)
 
+Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin but since his repository isn't maintained anymore we forked it on the 19th December of 2023 and have been keeping it up-to-date and expanding on the features since then. 
 [Buy Sergey a ☕](https://www.buymeacoffee.com/SergeyLukin) 
 
-Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin. Repo can be found [here.](https://github.com/onixpro/mkdocs-drawio-file)
-
 ## Features
 This plugin enables you to embed interactive drawio diagrams in your documentation. Simply add your diagrams like you would any other image:
 

example/docs/configuration.md

@@ -0,0 +1,70 @@
+# Configuration
+
+## Diagram options
+
+By default the plugin uses the official url for the minified drawio javascript library. To use a custom source for the drawio viewer you can overwritte the url. This might be useful in airlocked environments.
+
+```yaml
+plugins:
+  - drawio:
+      viewer_js: "https://viewer.diagrams.net/js/viewer-static.min.js"
+```
+
+Further options are the following with their default value:
+
+```yaml
+plugins:
+  - drawio:
+      # Control if hovering on a diagram shows a toolbar for zooming or not
+      toolbar: true
+
+      # Control if tooltips will be shown (data-tooltips)
+      tooltips: true
+
+      # Control if edit button will be shown in the lightbox view
+      # (data-edit)
+      edit: true
+
+      # Increase or decrease the padding around your diagrams
+      # (data-border)
+      border: 5
+```
+## HTML Attributes
+For each global configuration option you can also use the attribute in the diagram itself. This will override the global configuration. Here is an example:
+```markdown
+![](my-diagram.drawio){ data-toolbar-zoom="false" }
+```
+
+To use these attributes you need to enable the markdown extension `attr_list` in your `mkdocs.yml`:
+
+```yaml
+markdown_extensions:
+  - attr_list
+```
+## Material Integration
+
+If you are using the Material Theme and want to use the [instant-loading](https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/?h=instant#instant-loading) feature. You will have to configure the following:
+
+In your `mkdocs.yaml`:
+
+```yaml
+theme:
+  name: material
+  features:
+    - navigation.instant
+
+plugins:
+  - drawio
+
+extra_javascript:
+  - https://viewer.diagrams.net/js/viewer-static.min.js
+  - javascripts/drawio-reload.js
+```
+
+Add `docs/javascripts/drawio-reload.js` to your project:
+
+```js
+document$.subscribe(({ body }) => {
+  GraphViewer.processElements()
+})
+```

example/docs/index.md

@@ -1 +1,64 @@
-# MkDocs Drawio Plugin Tests
+# MkDocs Plugin for embedding Drawio files
+
+This plugin allows you to embed draw.io diagrams in your MkDocs documentation. It is compatible with most MkDocs themes, but specifically tested with the Material theme and the MkDocs default theme.
+
+Sergey ([onixpro](https://github.com/onixpro)) is the original creator of this plugin but since his repository isn't maintained anymore we forked it on the 19th December of 2023 and have been keeping it up-to-date and expanding on the features since then. 
+[Buy Sergey a ☕](https://www.buymeacoffee.com/SergeyLukin) 
+
+## Installation
+
+Install the plugin using pip or poetry:
+
+```bash
+pip install mkdocs-drawio
+```
+
+or
+
+```bash
+poetry add mkdocs-drawio
+```
+
+Then add the plugin to your `mkdocs.yml`:
+
+```yaml
+plugins:
+  - drawio
+```
+
+## Features
+
+The currently supported features are:
+
+* Embed draw.io diagrams as normal markdown images in your documentation.
+* Use diagrams hosted within your own docs or external urls.
+* Support for multi page diagrams by selecting which page to display.
+* Compatible with `mkdocs-caption` and `mkdocs-glightbox`.
+* Print and edit button.
+
+## Usage
+
+
+Simply add an image as you would normally do in markdown:
+
+```markdown
+Absolute path:
+![](/assets/my-diagram.drawio)
+
+Same directory as the markdown file:
+![](my-diagram.drawio)
+
+Relative directory to the markdown file:
+![](../my-diagram.drawio)
+
+
+Or you can use external urls:
+![](https://example.com/diagram.drawio)
+```
+
+Additionally this plugin supports multi page diagrams by using the `alt` text to select the pages by name:
+
+```markdown
+![Page-2](my-diagram.drawio)
+![my-custom-page-name](my-diagram.drawio)
+```

example/docs/plumbing.md

@@ -0,0 +1,57 @@
+# Plumbing and internals
+
+For those who want to understand how the plugin works, here is a brief overview.
+
+## Diagrams.net
+
+**Diagrams.net** or **Draw.io** is a free online diagram software. It is great for creating diagrams, flowcharts, process diagrams, and more. 
+
+It relies on JTGraph's [mxGraph](https://jgraph.github.io/mxgraph/) library to render the diagrams. A mxGraph is a XML-based language that defines the structure of the diagram. Here an example
+
+![](circle-square.drawio)
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="app.diagrams.net" version="26.0.7">
+  <diagram name="Page-1" id="mV4jbraemd7C51ydpzk2">
+    <mxGraphModel dx="565" dy="355" grid="1" gridSize="10"
+        guides="1" tooltips="1" connect="1" arrows="1" fold="1"
+        page="1" pageScale="1" pageWidth="394" pageHeight="394"
+        math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="7JHgTfKEjFP575Ptm9la-1" value=""
+            style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;"
+            vertex="1" parent="1">
+          <mxGeometry x="80" y="40" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="7JHgTfKEjFP575Ptm9la-2" value=""
+            style="whiteSpace=wrap;html=1;aspect=fixed;
+                   fillColor=#f8cecc;strokeColor=#b85450;"
+            vertex="1" parent="1">
+          <mxGeometry x="180" y="40" width="80" height="80" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
+```
+
+## Plumbing
+
+The plugin heavily relies on the Draw.io GraphViewer to render diagrams. The plugin itself is only responsible for replacing markdown references of drawio diagrams with the actual content of the files, passing configuration options to the viewer library and ensure compatibility across MkDocs themes. 
+
+Furthermore, it provides a way to extract pages from diagrams to only serve the necessary content to the user. This is useful when you have a large diagram and only want to show a specific part of it.
+
+How the plugin processes diagrams:
+
+1. mkdocs itself generates HTML for each markdown file in your docs.
+2. `mkdocs-drawio` then attaches to the `on_post_page` event. For more details, please have a look at the [event lifecycle documentation](https://www.mkdocs.org/dev-guide/plugins/#events)
+3. Adds the drawio viewer javascript reference
+4. Searches through the generated HTML for all `img` tags that reference a file with the extension `.drawio`
+5. Replaces the found `img` tags with `mxgraph` HTML block (actual drawio file content). For more details, please have a look at the [official drawio.com documentation](https://www.drawio.com/doc/faq/embed-html).
+
+By default this plugin uses the [GraphViewer](https://github.com/jgraph/drawio/blob/dev/src/main/webapp/js/viewer-static.min.js) minified version.
+
+This is a standalone viewer for drawio diagrams that can be embedded in any web page to convert mxGraph XML to SVG. It features a lightbox mode and a toolbar with buttons to zoom, edit, and navigate the diagram.

example/docs/tests/code-blocks/index.md

@@ -1,5 +1,17 @@
-# Diagrams are not rendered in code blocks
+# Code Blocks
 
-```bash
+Diagrams are not rendered in code blocks.
+
+## Example
+
+```markdown
 ![test diagram](test.drawio)
 ```
+
+## Markdown
+
+```
+ ```markdown
+ ![test diagram](test.drawio)
+ ```
+```

example/docs/tests/error-handling/index.md

@@ -1,12 +1,22 @@
 # Error Handling
 
-You should see an invalid diagram below:
+In the following case the diagram is not valid should show an error message `Not a diagram file`.
+
+## Example
 
 ![](test.drawio)
 
-You should see a warning in your mkdocs server similar to:
+
+Additionnaly, you should see a warning in your MkDocs server similar to:
 
 ```bash
 WARNING -  Warning: Found 0 results for page name 'test diagram' for diagram 'test.drawio' on path '/tmp/mkdocs_ce1qjhyn/test2'
 ERROR   -  Error: Provided diagram file 'test.drawio' on path '/tmp/mkdocs_ce1qjhyn/test5' is not a valid diagram
 ```
+
+## Markdown
+
+```markdown
+![](test.drawio)
+```
+

example/docs/tests/external-url/index.md

@@ -1,3 +1,12 @@
-# Test to use url instead of file path
+# External URL
 
-![](http://127.0.0.1:8000/tests/assets/test.drawio)
+## Example
+This is an example of an external URL taken from jgraph:
+
+![](https://raw.githubusercontent.com/jgraph/drawio-diagrams/dev/examples/gemfile-dependency-graph.drawio)
+
+## Markdown
+
+```markdown
+![](https://raw.githubusercontent.com/jgraph/drawio-diagrams/dev/examples/gemfile-dependency-graph.drawio)
+```

example/docs/tests/pagging/index.md

@@ -1,16 +1,26 @@
 # Pagging
 
-Below you should see Page-1 (default) because the alt text is not found:
+## Examples
+
+Below you should see diagram Page-1:
+![Page-1](test.drawio)
+
+Below you should see diagram Page-2:
+![Page-2](test.drawio)
+
+Below you should see Page-1 (default) because the specified Page-3 has not been found:
 ![test diagram](test.drawio)
 
 Furthoremore, you should see a warning in your mkdocs server similar to:
 
 ```bash
-WARNING -  Warning: Found 0 results for page name 'test diagram' for diagram 'test.drawio' on path '/tmp/mkdocs_ce1qjhyn/test2'
+WARNING -  Warning: Found 0 results for page name 'Page-3' for diagram 'test.drawio' on path '/tmp/mkdocs_ce1qjhyn/test2'
 ```
 
-Below you should see diagram Page-1:
-![Page-1](test.drawio)
+## Markdown
 
-Below you should see diagram Page-2:
+```markdown
+![Page-1](test.drawio)
 ![Page-2](test.drawio)
+![Page-3](test.drawio)
+```