asciidoctor / atom-asciidoc-image-helper

⚛ Tool to make insertion of images into AsciiDocs easier in the Atom editor.

ℹ️ Information ℹ️

GitHub is sunsetting Atom on December 15, 2022.
As a result, we recommend migrating to an alternative solution. The Asciidoctor community is now focusing on providing the best writing experience using the IntelliJ platform or Visual Studio Code.

On December 15, 2022, this repository will be archived.

---

AsciiDoc Image Helper

An Atom plugin to facilitate insertion of images in an AsciiDoc document.

Create an image file, in the specified folder, that is named after the AsciiDoc file it is pasted into, and insert an image reference to that file into the editor.

Originally forked from markdown-image-helper.

Basic Usage

1. Take a screenshot or copy an image to the clipboard.
2. Paste it into Atom AsciiDoc editor.
3. See that the 'Images Folder' has a new png file, and an image reference was inserted into the editor with the correct filename.

The default setting is to place copied and created a folder named images in the same folder as the document.
Another default setting is to expect that the :imagesdir: attribute is not set in the document (or through cli) and sets the 'Append Images Folder' setting to true. This setting will append the Images Folder path to the filename in the image:[] macro so that AsciiDoctor knows where to find the files.

NOTE: To increase flexibility for moving your images folder, and to also reduce the repetition of hard coded image folder strings in the document; it is recommended to set the :imagesdir: attribute for your document to match the 'Images Folder' setting in this package and to disable the 'Append Images Folder' option.
This way, the package will know where to place your image files, and asciidoctor will know where to find them.

If you want to move your folder of images into a new directory called something like assets you would change the Folder Location string to assets/images, and set this same thing as the value of the :imagesdir: attribute in the document.
Make sure the setting to 'Append Images Folder' is not checked.
Now everything should just work as expected in the new location, without requiring a Find/Replace operation over all of the documents that have hard coded the images folder into the image macros.

Notes for Windows Users

To take a screenshot to the clipboard.

Use PrintScr to capture your entire desktop.
Use Alt + PrintScr to capture the active window.

When copying an existing file on your local system into the document.

1. Open Windows Explorer and find your file.
2. Press Shift and right-click with your mouse.
3. Your pop up menu will have several more options.
4. Select Copy as Path.
5. Paste into the editor.

Notes for Mac OS X Users

To take a screenshot to the clipboard.

Use Command-Shift-Control-4 to capture the image data to the clipboard.

When copying an existing file on your local system into the document.

1. Navigate to the file or folder you wish to copy the path for.
2. Right-click (or Control+Click, or a Two-Finger click on trackpads) on the file in the Mac Finder.
3. While in the right-click menu, hold down the OPTION key to reveal the "Copy (item name) as Pathname" option, it replaces the standard Copy option.
4. Once selected, the file or folders path is now in the clipboard, ready to be pasted into the document.
   Note: The copied pathname is always the complete path, it’s not relative.

Install

Settings/Preferences > Install > Search for asciidoc-image-helper

or

apm install asciidoc-image-helper

Credits

Special thank you to Ludovic Fernandez 'ldez' for turning this package into a legit project. I am learning a lot from his pull requests.

atom-asciidoc-image-helper's Issues

Place image in Absolute Path

I want to paste an image in an Asciidoc document, but the image should be stored in an absolute path.
When I try to provide an absolute path to asciidoc-image-helper, the macro inside atom is generated correctly, but the image is placed at a relative path.

I created a small example that as I hope explains it well.
example.txt

System information:
MacOS Mojave 10.14.2

By the way I want to say thanks for the great work and the nice package!

Add ability to modify the filename

Original report from @chuckf at: https://github.com/bwklein/asciidoc-image-helper/issues/2

Currently a pasted image uses the name of the doc and a hash as the file name when it is pasted in.
I would like the ability to modify the file name that is used when pasting an image into the document.

My thought would be this is either a pop up dialog box for complete naming flexibility or an option to add a custom field to the file name.

Currently it is my_asciidoc_file-56fe6.png

A custom field might allow me to put my name or other identifier in there for image tracking purposes.

The custom field would make it look something like this my_asciidoc_file-56fe6-chuck.png

Problem with image folder path when the document name has spaces

Steps to reproduce the problem:

1. Create an asciidoc with an space in the name
2. Check 'Place images in folder that is the same as the filename' in config
3. Check 'Append imagesFolder in generated links.' in config
4. Paste an image

The url of the image will be:

image::Asciidoc Test\Asciidoc_Test-9b7ee.png[]

The viewer can't render the image because of the spcace in the path.

This path should be encodeURI when it was write

Downloads count is not correct in Atom Package Badge.

If you look at the ReadMe badge for the https://atom.io/packages/asciidoc-image-helper package. There are downloads shown on the package page, but the number shows 0 in the badge. Probably a bad badge URL.

Uncaught TypeError: clipboard.readImage(...).toPng is not a function

[Enter steps to reproduce:]

1. Copy an image to clipboard
2. Paste in asciiddoc document

Atom: 1.28.0 x64
Electron: 2.0.3
OS: Mac OS X 10.13.5
Thrown From: asciidoc-image-helper package 1.0.0

Stack Trace

Uncaught TypeError: clipboard.readImage(...).toPng is not a function

At /Users/mgr/.atom/packages/asciidoc-image-helper/lib/main.coffee:51

TypeError: clipboard.readImage(...).toPng is not a function
    at Object.pasteNativeImage (/packages/asciidoc-image-helper/lib/main.coffee:51:39)
    at /packages/asciidoc-image-helper/lib/main.coffee:35:12
    at Function.module.exports.Emitter.simpleDispatch (/Applications/Atom.app/Contents/Resources/app/node_modules/event-kit/lib/emitter.js:27:20)
    at Emitter.module.exports.Emitter.emit (/Applications/Atom.app/Contents/Resources/app/node_modules/event-kit/lib/emitter.js:156:34)
    at CommandRegistry.handleCommandEvent (/Applications/Atom.app/Contents/Resources/app/src/command-registry.js:360:24)
    at KeymapManager.module.exports.KeymapManager.dispatchCommandEvent (/Applications/Atom.app/Contents/Resources/app/node_modules/atom-keymap/lib/keymap-manager.js:621:22)
    at KeymapManager.module.exports.KeymapManager.handleKeyboardEvent (/Applications/Atom.app/Contents/Resources/app/node_modules/atom-keymap/lib/keymap-manager.js:412:28)
    at WindowEventHandler.handleDocumentKeyEvent (/Applications/Atom.app/Contents/Resources/app/src/window-event-handler.js:110:40)

Commands

     -1:51.2.0 editor:select-to-end-of-line (input.hidden-input)
     -1:50.7.0 core:select-left (input.hidden-input)
     -1:50 core:backspace (input.hidden-input)
  5x -1:46 core:move-down (input.hidden-input)
  2x -1:42.3.0 editor:newline (input.hidden-input)
  6x -1:32.7.0 core:move-left (input.hidden-input)
     -1:30 editor:move-to-end-of-screen-line (input.hidden-input)
 15x -1:15.9.0 core:backspace (input.hidden-input)
     -1:13.5.0 autocomplete-plus:confirm (input.hidden-input)
     -1:13.5.0 snippets:expand (atom-text-editor.editor.is-focused.autocomplete-active)
     -1:13.3.0 editor:newline (input.hidden-input)
  2x -1:12.2.0 core:backspace (input.hidden-input)
     -1:10.2.0 core:move-right (input.hidden-input)
     -1:08.8.0 editor:select-to-end-of-line (input.hidden-input)
     -1:08.1.0 core:backspace (input.hidden-input)
  2x -1:07.3.0 editor:newline (input.hidden-input)

Non-Core Packages

activate-power-mode 2.7.0 
asciidoc-assistant 0.2.2 
asciidoc-image-helper 1.0.0 
asciidoc-preview 2.12.1 
atom-beautify 0.32.5 
atom-grails 1.2.0 
atom-language-velocity 1.1.0 
atomic-chrome 0.3.3 
autocomplete 0.47.0 
autocomplete-asciidoc 0.1.2 
autocomplete-java 1.2.7 
autocomplete-xml 0.10.1 
darkula-ui 0.1.0 
dash 1.7.1 
file-icons 2.1.21 
intellij-idea-keymap 0.2.3 
java-generator 2.2.3 
language-asciidoc 1.11.0 
language-groovy 0.7.0 
language-kotlin 0.5.0 
language-plantuml 0.2.0 
minimap 4.29.8 
native-ui 0.26.2 
pigments 0.40.2 
plantuml-viewer 0.7.2 
pretty-json 2.0.1 
Quick-JavaScript 2.2.0 
slime 2.4.0 
split-diff 1.5.2 
teletype 0.13.3 
xml-formatter 0.11.0 

Thumbnail linked to full image

Most of the time the images I need to display are quite big and it would be handy to generate a thumbnail linked to the full image.
Using the width I can control the size of the displayed image and the full sized image can be accessed following the link.

Example of generated asciidoc:
image::images\new.png[My picture,width=200,link="images\new.png"]

Place images in folder that is the same as the filename without the extension.

In Middleman, there is an option to keep images in subdirectories that match the article filename.
As the file/folder name will change from file to file, it would be good to offer an option to place images in a folder named after the filename. This will offer a dynamic image folder name, and override the "Images Folder" setting.

This would also automatically add the folder name to the path in the image macro, unless the Append Images Folder option is disabled (enabled by default.)

Target of image macro incorrect when imagesdir attribute is set

When the imagesdir attribute is set to a value other than blank, the image is placed into the correct location, but the target of the image macro is not correct. The target includes the value of the imagesdir.

Example:

= Document Title
:imagesdir: images

Paste an image. The image appears at the following location:

images/test-52db5.png

The AsciiDoc document ends up as:

= Document Title
:imagesdir: images

image::images/test-52db5.png[]

The image macro should be written as follows:

image::test-52db5.png[]

Notice that the value of the imagesdir is stripped away from the start of the target.

Unpublish the old package

@bwklein I'm going to unpublish the plugin from your repository and publish from here.

URL support not working on Mac OS X

Report from @chuckf originally on https://github.com/bwklein/asciidoc-image-helper/issues/20

Using Atom 1.7.3 and asciidoc-image-helper 0.9.2, when I paste a path to an image file that path pastes in and does not convert to an image:: link as expected.

The test path I have used is:

/Users/chuckf/Downloads/splunk.png
/Users/chuckf/Downloads/splunk.jpg

Expected result is

image::splunk.png
image::splunk.jpg

Actual result:

/Users/chuckf/Downloads/splunk.png
/Users/chuckf/Downloads/splunk.jpg

NOTE: When pasting similar paths on a Fedora box, same versions of the software, the URLs are converted to image:: links as expected.

I don't get a success or error message popup.

I opened the console window with cmd-alt-i (for future reference) and did not see any errors occur when pasting in the link.

I typed the paths into a text editor, HTML page, and ran the command ls /Users/chuckf/Downloads/splunk.png into the native terminal and iterm2. I then selected the text and copied using cmd-c and pasted into Atom using cmd-v.