/chatu

Quickly insert a generated image to orgmode or markdown, fast and conveniently.

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

Introduction

A small tool to various files to .svg files or download image files, and insert it to orgmode or markdown on-the-fly.

插 chā 图 tú: insert a diagram.

Install

Before using chatu, you may need to install some external programs and set them in your PATH:

  • draw.io and pdf2svg for drawio file conversion
  • plantuml.jar, java for plantuml
  • babashka for .bb script
  • curl for downloading file from web

From melpa with use-package:

(use-package chatu
  :hook ((org-mode markdown-mode) . chatu-mode)
  :commands (chatu-add
             chatu-open)
  :custom ((chatu-input-dir "./draws")
           (chatu-output-dir "./images")))

Or git submodule and use-package

(use-package chatu
  :load-path "~/.emacs.d/site-lisp/chatu"
  :hook ((org-mode markdown-mode) . chatu-mode)
  :commands (chatu-add
             chatu-open)
  :custom ((chatu-input-dir "./draws")
           (chatu-output-dir "./images")))

Usage

Add chatu line with chatu-new command:

#+chatu: :drawio "diagram.drawio" :page 0 :input-dir "./draws" :output-dir "./images" :output "diagram.svg" :crop :nopdf

<!-- #+chatu: :drawio "diagram.drawio" :page 0 :input-dir "./draws" :output-dir "./images" :output "diagram.svg" :crop :nopdf -->

Options/Settings:

  • :drawio specifies the backend, they can be :planuml, :babashka, :curl or others added in the future by you.
  • file name after backend keyword is the input file name.
  • :page species which page you want to import to buffer.
  • :input-dir and :output-dir are the folders for input or output file.
  • :output is the output file name.
  • :crop if you want to crop the empty white in page.
  • :nopdf if you do not want intermediate pdf file for drawio backend.

Move cursor to chatu line,

  • C-c C-c will invoke chatu-add to add image in orgmode.
  • C-c C-c C-c will invoke chatu-add to add image in markdown-mode.
  • C-c C-o will invoke chatu-open to open original .drawio or .puml file.

chatu line means different in orgmode and markdown:

  • #+chatu: :drawio or #+chatu: :plantuml in orgmode
  • <-- #+chatu: :drawio --> or <-- #+chatu: :plantuml --> in markdown

Remind!

  • the input files should be the first parameter, for example, .drawio or .puml file.
  • in order to support whitespace in file and dir name, please "quote all of them".

Extension

You can easily extend this package by adding new chatu-<tool>.el. For example, when <tool> = drawio, you need to define chatu-drawio-open and chatu-drawio-script in chatu-drawio.el.

  • chatu-drawio-open is invoked to open the drawio input file at the line.
  • chatu-drawio-script is used to generate the shell script for conversion.

Both method use a keyword-plist parameter, which contains the chatu settings from chatu line.

#+chatu: :drawio "diagram.drawio" :page 0 :input-dir "./draws" :output-dir "./images" :output "diagram.svg" :crop :nopdf

For example, we can get following keyword-plist from above chatu line:

(:chatu t :type "drawio"
 :input "diagram.drawio" :output "diagram.svg" :page "0"
 :input-dir "./draws" :output-dir "./images"
 :input-path "./draws/diagram.drawio"
 :output-path "./images/diagram.svg"
 :crop t
 :nopdf t)

Usage

See example chatu.org in orgmode and chatu.md in markdown-mode.

Simple Usage

org-mode:

#+chatu: :drawio "diagram.drawio"
#+chatu: :plantuml "diagram.puml"
#+chatu: :curl "http://example.org/image.svg"
#+chatu: :babashka "babashka.bb"

markdown-mode:

<!-- #+chatu: :drawio "diagram.drawio" -->
<!-- #+chatu: :plantuml "diagram.puml" -->
<!-- #+chatu: :curl "http://example.org/image.svg" -->
<!-- #+chatu: :babashka "babashka.bb" -->

Omit the extension

org-mode:

#+chatu: :drawio "diagram"
#+chatu: :plantuml "diagram"

markdown-mode:

<!-- #+chatu: :drawio "diagram" -->
<!-- #+chatu: :plantuml "diagram" -->

Add more properties

org-mode:

#+chatu: :drawio "diagram"
#+name: workflow
#+caption: chatu workflow

Extract specific page

org-mode:

#+chatu: :drawio "diagram.drawio" :page 1
#+chatu: :plantuml "diagram.puml" :page 1

markdown-mode:

<!-- #+chatu: :drawio "diagram.drawio" :page 1 -->
<!-- #+chatu: :plantuml "diagram.puml" :page 1 -->

Even more specific

Add input-dir, output-dir and output file name

org-mode:

#+chatu: :drawio "diagram.drawio" :page 0 :input-dir "./draws" :output-dir "./images" :output "diagram.svg"

markdown-mode:

<!-- #+chatu: :drawio "diagram.drawio" :page 0 :input-dir "./draws" :output-dir "./images" :output "diagram.svg" -->

Contributors