Skip to content

Instantly share code, notes, and snippets.

@shivanshu-semwal

shivanshu-semwal/excalidraw.md

Created November 26, 2022 19:09
Show Gist options
  • Star 1 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save shivanshu-semwal/52a6d024b0e72be5b3ba0247fc7c7840 to your computer and use it in GitHub Desktop.
Save shivanshu-semwal/52a6d024b0e72be5b3ba0247fc7c7840 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
excalidraw.md

Excalidraw

The Obsidian-Excalidraw plugin integrates Excalidraw, a feature rich sketching tool, into Obsidian. You can store and edit Excalidraw files in your vault, you can embed drawings into your documents, and you can link to documents and other drawings to/and from Excalidraw. For a showcase of Excalidraw features, please read my blog post here and/or watch the videos below.

Please upgrade to Obsidian v0.12.19 or higher to get the latest release.

Video walkthrough

  1. Getting Started
  2. Basic shapes and features
  3. Groups
  4. Stencil
  5. embedding
  6. Links
  7. Markdown
  8. Templates
  9. Excalidraw Automate
  10. Miscellaneous

Features

  • The plugin integrates Excalidraw seamlessly into Obsidian including Command Palette actions, File Explorer features, Option Menu commands, and the Ribbon Button.
  • CTRL/CMD+Click on the ribbon button, or in the file explorer to create / open drawings in a new pane.

Settings

Settings will allow you to customize Excalidraw to your needs:

  • Default folder for new drawings and define custom filename pattern for new drawings.

Templates

  • Template for new drawings. The template will restore stroke properties. This means you can set up defaults in your template for stroke color, stroke width, opacity, font family, font size, fill style, stroke style, etc. This also applies to ExcalidrawAutomate.
    • Via the template you can customize the color palette used by Excalidraw.
      • Switch to Markdown view.
      • Scroll down to the bottom of the file and find "AppState": {.
      • Find "customColorPalette": { at the end of the AppState section.
      • You may specify the 3 palettes used in Excalidraw by adding any or all of the following 3 variables:
        • "canvasBackground":[], "elementBackground":[], "elementStroke": [].
      • Add a comma separated list of valid HTML colors (e.g. #FF0000 for red) in the array for each of the variables.
      • See my videos above for further help.

Export

  • If portability is important to you:

    • Auto-export SVG and/or PNG files including keep-in-sync feature so you can embed SVG/PNG into your documents instead of embedding excalidraw files.
    • You can override export settings for an individual file by adding the excalidraw-autoexport frontmatter key. Valid values for this key are none, both, png and svg.

  • Specify the default width of embedded drawings.

  • Compatibility features to auto-export and keep in sync markdown excalidraw files and legacy .excalidraw files.

  • Experimental feature to add custom TAG to file explorer to mark drawing files.

  • Enable / disable autosave.

Embedded images

  • You can customize the size and position of the embedded images using the
    • ![[image.excalidraw|100]],
    • ![[image.excalidraw|100x100]],
    • ![[image.excalidraw|100|left]],
    • ![[image.excalidraw|right-wrap]], formatting options.
    • ![[<filename.excalidraw>|<width>x<height>|<alignment>]].
    • You can add your custom alignment via CSS.
    • Any text that appears in <alignment> will be added to the rendered SVG element style and to the wrapper DIV element.
    • See styles.css for more insight.

Hyperlinks

  • Supports hyperlinks e.g.
    • https://zsolt.blog,
    • [Obsidian](https://obsidian.md), and
    • internal links e.g. [[My file in vault|Alias]] in drawing text.
  • Links will update when files are moved or renamed, if you have the Obsidian setting Files & Links/Automatically Update Internal Links enabled.
  • Links in drawings will show up in backlinks of documents
  • Transclusions are supported
    • ![[myfile#^blockref]] will convert in the drawing into the transcluded text of the block
    • ![[myfile#section]] also works, this will transclude the section
    • you can also specify word wrapping for transcluded text by adding the max character count in curly brackets right after the transclusion e.g. ![[myfile#^blockref]]{40} will wrap text at 40 characters.
  • For convenience you can also use the command palette to insert links into drawings
  • CTRL/CMD + hover to bring up the Obsidian quick preview for the link. (On Mac it is CTRL+CMD+hover).
  • CTRL/CMD + CLICK a text element to open it as a link.
  • CTRL/CMD + ALT + CLICK to create the file (if it does not yet exist) and open it
  • CTRL/CMD + SHIFT + CLICK to open the file in a new pane
  • CTRL/CMD + ALT + SHIFT + CLICK to create the file (if it does not yet exist) and open it in a new pane
  • Using the block reference you can also reference & transclude text that appears on drawings, in other documents

LaTeX

Insert LaTeX formulas using the Command Palette action "Insert LaTeX formula". You can edit formulas either in Markdown view, or by CTRL/CMD + Click on the formula.

Drag & Drop support

  • You can drag files from the Obsidian file explorer and they will become links to those files in Excalidraw.
  • Dragging image files (PNG, SVG, JPG, ICO, GIF, WEBP, Excalidraw) from Obsidian's file explorer while pressing the CTRL (SHIFT on Mac) button will embed the image into your drawing.
    • If in addition to CTRL or SHIFT you also hold down ALT, the image will be inserted at 100% of its size.
    • Note: this is a very niche feature with a very particular behavior that I built primarily for myself
    • (even more so than other features in Excalidraw Obsidian - also built primarily for myself 😉).
    • This will reset your embedded image to 100% size every time you open the Excalidraw drawing, or in case you have embedded an Excalidraw drawing on your canvas inserted using this function, every time you update the embedded drawing, it will be scaled back to 100% size.
    • This means that even if you resize the image on the drawing, it will reset to 100% the next time you open the file or you modify the original embedded object. This feature is useful when you decompose a drawing into separate Excalidraw files, but when combined onto a single canvas you want the individual pieces to maintain their actual sizes. I use this feature to construct Book-on-a-Page summaries from atomic drawings.
  • You can drag and drop text from Markdown views onto Excalidraw.
  • You can drag and drop web addresses from your browser and they will become links.

Image support

  • On iOS and Android you can add images from your camera by pressing the add image button in Excalidraw.
  • You can copy/paste images into your drawing. Images will be saved in your vault.
  • You can drag and drop images as explained above.

Block referencing parts of images

  • When referencing an element on the canvas in a link pointing to an Excalidraw file using
    • the elementId or the section header (i.e. a Text Element containing the # <Section title>)
      • e.g. [[file#^elementID]],
    • you can add the group= prefix,
      • e.g. [[file#^group=elementID]] or
    • the area= prefix,
      • e.g. [[file#area=Section heading]].
    • If the group= prefix is found Excalidraw will select the group of elements in the same group as the element referenced by the elementID (block reference) or the section heading.
    • If the area= prefix is found Excalidraw will insert a cutout of the image around the referenced element.
    • Note that the area= selector is not supported when embedding Excalidraw as PNG into your markdown documents.
    • Referencing the elementID of a text element without the group= or area= prefix will transclude the element as plain text. Referencing a non-Text Element (e.g. rectangle, ellipse, etc.) without the group= or area= prefix will result in an Obsidian error since these elementIds are not present in the Excalidraw markdown file as block references.

Markdown

  • Since 1.2.0 Drawing files are stored in Markdown files
    • You can add tags to drawings
    • You can add metadata to the YAML front matter of drawings
    • Anything you add between the frontmatter and the # Text Elements heading will be ignored by Excalidraw, i.e. you can add whatever you like here, it will be preserved as part of the document.
    • Excalidraw documents now show in graph view.
    • The following front matter keys will customize how the drawing is displayed - overriding general settings:
      • excalidraw-link-prefix: "📍" preview prefix for internal links
      • excalidraw-url-prefix: "🌐" preview prefix for external links
      • excalidraw-link-brackets: true|false whether or not to display brackets around links in preview
      • excalidraw-default-mode: view|zen Open this document in view mode or zen mode by defult. Default view mode is excellent for presentation slides.
    • Frontmatter tags to customize image export at a file level 519. If these keys are present they will override the default excalidraw embed and export settings.
      • excalidraw-export-transparent: true: true == Transparent / false == with background.
      • excalidraw-export-dark: true == Dark mode / false == light mode.
      • excalidraw-export-padding: Specify the export padding for the image
      • excalidraw-export-pngscale: This only affects export to PNG. Specify the export scale for the image. The typical range is between 0.5 and 5, but you can experiment with other values as well.

Embed complete markdown files into your drawings

  • Drag from the desired file from the Obsidian file explorer and hold down CTRL/CMD while dropping the file onto the canvas.
  • Use the command palette action: Insert markdown file from vault
  • Use custom woff, woff2 or TTF font to display the document, you can set the default font to use under Excalidraw Settings.
  • You can set a custom css for rendering the snapshot image of your markdown document. Only operating system standard fonts are supported as the font-family ( Win10, Mac & iOS ), plus you can set one additional custom font using the setting explained above.
    • (for a demonstration watch this video and check out this
    • sample css).
    • To help with styling you can observe the SVG snapshot of the markdown document created by Excalidraw.
      • Open Obsidian Developer Console (CTRL+Shift+i) and
      • execute the following command: ExcalidrawAutomate.mostRecentMarkdownSVG
  • You can control appearance of the embedded markdown file on a file by file bases by adding the following front matter keys to your markdown document:
    • excalidraw-font: Virgil|Cascadia|font_file_name.extension
    • excalidraw-font-color: css-color-name|#HEXcolor|any-other-html-standard-format,
      • you can find css color names here.
    • excalidraw-border-color: css-color-name|#HEXcolor|any-other-html-standard-format
    • excalidraw-css: "css-filename|css snippet"
  • Switch to markdown view or use CTRL/CMD+ALT/OPT click on the image to edit properties of the embed:
    • [[filename#^blockref|WIDTHxMAXHEIGHT]]

Other

  • Includes full
  • REQUIRES AN OBSIDIAN SYNC SUBSCRIPTION: Full drawing file history and synchronization between devices
  • Multilanguage support: if you'd like to help out by translating the plugin, please get in contact with me.

Feedback, questions, ideas, problems

Join the conversation about the Excalidraw plugin on forum.obsidian.md

Please head over to GitHub to report a bug or request an enhancement.

Say Thank You

If you are enjoying Excalidraw then please support my work and enthusiasm by buying me a coffee on https://ko-fi/zsolt.

Please also help spread the word by sharing about the Obsidian Excalidraw Plugin on Twitter, Reddit, or any other social media platform you regularly use.

You can find me on Twitter @zsviczian, and on my blog zsolt.blog.

Friends of Excalidraw

If you enjoy Excalidraw, consider giving ExcaliBrain a try (also available via Obsidian Community Plugins).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment