= krokidile Sebastian Sommerfeld sebastian@sommerfeld.io :github-org: sommerfeld-io :project-name: krokidile :url-project: https://github.com/{github-org}/{project-name} :github-actions-url: {url-project}/actions/workflows :job: pipeline.yml :badge: badge.svg

Krokidile is a web-based Live-Editor for Diagrams to use with link:https://kroki.io[Kroki.io].

image:{github-actions-url}/{job}/{badge}[Github Badge, link={github-actions-url}/{job}]

• Github Repository -> {url-project}
• DockerHub -> https://hub.docker.com/r/sommerfeldio/{project-name}
• Where to file issues -> {url-project}/issues

This project is a web-based live editor for diagrams, enabling developers to see a real-time preview of their diagrams as they write the diagram code. This immediate feedback loop makes it easier to create and modify diagrams, as developers can instantly see the impact of their changes.

Diagrams are rendered with Kroki. Kroki is a tool that renders diagrams from code allowing developers to write diagrams as code.

The main advantage of using diagrams as code is that it allows for version control, collaboration, and automation, just like any other piece of code in your repository

Krokidile provides a web-based live editor for diagrams, enabling developers to see a real-time preview of their diagrams as they write the code. This immediate feedback loop makes it easier to create and modify diagrams, as developers can instantly see the impact of their changes.

== Features

• Real-time preview of diagrams based on diagram code
• Export diagrams as PNG or SVG image
• Save the diagram code as a file
• Supported diagram types BlockDiag Ditaa C4 with PlantUML Erd (Entity-Relationship Diagram) Mermaid PlantUML RackDiag Structurizr // (see https://kroki.io) // * Configure Krokidile to use your own Kroki instance (e.g., for self-hosting or to ensure your diagram data is kept private)

=== Code editor behavior When the diagram type is changed the editor is populated with an example code of the selected diagram type. However, when code is changed by the user, the code is stored in the browsers local storage and will be loaded when the page is reloaded to ensure the user does not lose their work when accidentally reloading the page.

This conflicts with displaying the example code of the selected diagram type. The code written by the user is more important than the example code. Therefore, the example code is not displayed when the user has written code.

To reset the editor content to the example code of the selected diagram type, the user can click the "Reset" button (the circle sign) next to the download buttons.

== How to use === Krokidile Application The only way to use Krokidile is to use the Docker image. The Docker image is available on Docker Hub at https://hub.docker.com/r/sommerfeldio/krokidile. [source, bash]

docker run --rm -p 3000:3000 sommerfeldio/krokidile:latest

// This Docker compose stack starts a kroki instance and Krokidile. The Krokidile instance is configured to use the kroki instance. The Environment variable KROKI_URL is mandatory, there is no default value. This Docker compose stack starts a Krokidile instance. The Krokidile instance uses https://kroki.io to convert diagram code into images. [source, yml]

services: krokidile: container_name: krokidile image: sommerfeldio/krokidile:latest ports:

• 3000:3000

=== Krokidile Documentation This project also publishes a documentation. The image is available on Docker Hub at https://hub.docker.com/r/sommerfeldio/krokidile-docs.

Start with plain Docker: [source, bash]

docker run --rm -p 3080:3000 sommerfeldio/krokidile-docs:latest

This Docker compose stack starts a Krokidile Dococumentation website. [source, yml]

services: docs: container_name: krokidile-docs image: sommerfeldio/krokidile-docs:latest ports:

• 3080:3000

== Development Consider the following steps to start developing on this project:

. Read the link:https://github.com/sommerfeld-io/krokidile/blob/main/docs/modules/ROOT/pages/development-guide.adoc[Development Guide] and link:https://github.com/sommerfeld-io/krokidile/blob/main/CONTRIBUTING.adoc[Contribute to this Project] pages. . Prepare the node environment with npm install. . Start the development server with the following command: npm run dev. // .. Keep in mind that the development server is not connected to a Kroki instance and will not render diagrams. To render diagrams, start Krokidile from its docker-compose stack.

The whole Docker stack can be built and started with docker compose build && docker compose up.

To use the DevContainer, open the project in VSCode and select "Reopen in Container" from the command palette. Having Visual Studio Code (VSCode) and the Dev Container plugin installed are essential prerequisites for this development environment. Docker, of course, is also mandatory.

=== Components The Frontend is built with React on top of Node.js. The Backend is a Kroki instance.

The Application consists of the following components:

[ditaa, "ditaa-diagram"]

          +-----------------+

The Docker Compose stacks from this repo feature some additional components that are not part of the application itself but are required to run some linting tasks etc. Because they are not part of the actual application, they are not listed here.

== Risks and Technical Debts link:{url-project}/issues?q=is%3Aissue+label%3Asecurity%2Crisk+is%3Aopen[All issues labeled as risk (= some sort of risk or a technical debt) or security (= related to security issues)] are tracked as Github issue and carry the respective label.

== Contact Feel free to contact me via sebastian@sommerfeld.io or visit my website https://www.sommerfeld.io.

// +---------------------------------------------------+ // | | // | DO NOT EDIT DIRECTLY !!!!! | // | | // | File is auto-generated by pipeline. | // | Contents are based on Antora docs. | // | | // +---------------------------------------------------+