Closed sturtison closed 1 year ago
You will set the builtin attribute imagesdir manually with a query parameter telling the browser extension where to find the images.
I absolutely do not want to encourage this behavior. This is setting a precedent of having to insert extra configuration per page, which is ultimately going to slow down writers. It also encourages the habit of setting imagesdir in the file itself, which makes AsciiDoc files more messy than they need to be. On top of that, it's only a partial solution since imagesdir cannot account for a reference to an image in another module, version, and/or component.
If the browser extension wants to recognize an Antora component and load an extension that resolves an Antora resource reference, that's fine. But I do no want to encourage users to manipulate imagesdir in this way. Please don't document this.
Thanks for the guidance in applying effort where best focused!
The best approach would then be to focus on #299.
At the same time as #652 add the following two use case: Preview a simple Antora component with images
Starting content for the use case below:
Preview an Antora component with images
(insert use case summary)
Antora components have their AsciiDoc pages and images in separate folders.
We will use a simple example with an AsciiDoc page and an image as follows:
Inside
file.adoc
, an image reference looks like:By default, the browser extension (as AsciiDoc does) will look for images in the current folder, so the image reference will not find the image file.
You will set the builtin attribute imagesdir manually with a query parameter telling the browser extension where to find the images. This reproduces what Antora does automatically on a larger scale.
Open
file.adoc
in the browser extension. The images do not show.To the end of the of
file.adoc
URL in tbe browser address bar, add?imagesdir=../images/
NOTE: The (/
) suffix is required. Press EnterThe page file.adoc is now rendered as HTML with images from
../images
.Learn more about the Antora images folder at https://docs.antora.org/antora/latest/images-directory/
Progressing from a simple asciidoc with images to Antora
Write your first draft in a single folder.
In file.adoc, reference your image.png like this:
When you are ready to move your content into an Antora component, file.adoc goes under pages/ images.png goes under images/
To now preview your content in the Antora component, use the Preview an Antora component with images use case.