Docs: Add Antora preview use case for the browser extension (Partial approach to #299. Won't do)
sturtison opened this issue · 2 comments
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:
.../pages/file.adoc
.../images/image.png
Inside file.adoc, an image reference looks like:
The image is shown below:
.my image caption
image::image.png[]
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.adocin the browser extension. The images do not show. -
To the end of the of
file.adocURL in tbe browser address bar, add?imagesdir=../images/
NOTE: The (/) suffix is required.
Press Enter
The 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.
file.adoc
image.png
In file.adoc, reference your image.png like this:
The image is shown below:
.my image caption
image::image.png[]
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.
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.