Document title, output directory and collapsible block questions

Hello there,

I started an asciidoc document and use VScode running on Windows. I have some questions, which I couldn't resolve by myself:

1. Document title
I would like to automatically set the document title from the filename (without suffix).

= {docfile}

does not seem to do the trick.

2. Output directory
I would like to specify e.g. "./output" as the dircetory for generated output (html, pdf, etc.), where output is a subdirectory of the directory, where the source asciidoc document is in.

3. Collapsible block and Section Headers
I have problems to get (continued) Section Headers in a collapsible block. It seems they are not recognized as headers, if in a collapsible block.

= Header 1
== Sub-Header

[collapsible%]
====
=== Sub-Sub-Header
====

In the document there is a collapsible section, which is doing fine - except that using Section Headers inside this section renders them as plain text showing the equal signs. Meaning, if the collapsible section is expanded the header appears as it is written in asciidoc: ==== Sub-Sub-Header
instead of "Sub-Sub-Header in bigger font size.

Produced output is html.

Can you give me a tip to help?

[EDIT: added the following question]
4. Auto-create image subfolder
BTW is it possible to automatically create the relative images subfolder, if it does not exists. It seem necessary before pasting the first image - otherwise the image gets lost.

Kind regards!

carsten-doctor wrote

1. Document title
I would like to automatically set the document title from the filename (without suffix).

= {docfile}

does not seem to do the trick.

Seems to be working in the cli so you'll be fine when generating the final result. The preview has some limitations, but this is something you can report to the repo https://github.com/asciidoctor/asciidoctor-vscode. I pressume it's failing in the preview because the converter is passing the content as string and not the file reference...but that's just me guessing.
Btw, I think you'd want to use {docname} instead, docfile includes the path (https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-reference/#intrinsic-attributes).

carsten-doctor wrote

2. Output directory
I would like to specify e.g. "./output" as the dircetory for generated output (html, pdf, etc.), where output is a subdirectory of the directory, where the source asciidoc document is in.

The VS Code plugin is a preview tool, it has some export features but is not intended for full conversion. Usually to generate the the final result you'll want to use a script using the CLI (Ruby, JS or Java) or some of the build tools available for the different languages.
Amongst other reasons, that's to ensure reproducibility and automation.
Feel free to ask here or join https://asciidoctor.zulipchat.com/.


Can't help with collapsible, sorry.

abelsromero wrote

Btw, I think you'd want to use {docname} instead, docfile includes the path

Yes, you are right :-)
But using "AsciiDoc: Save HTML document" from within VScode produces the same as the preview. ...see below

abelsromero wrote

The VS Code plugin is a preview tool, it has some export features but is not intended for full conversion. Usually to generate the the final result you'll want to use a script using the CLI (Ruby, JS or Java) or some of the build tools available for the different languages.

I am a little bit confused: what do I get by installing the VScode extension? Is it just syntax highlighting and the preview tool? Will output ("AsciiDoc: Save/Export .... ") still be generated through the preview module or will these commands (used from VScode command palette) call the CLI?

How should I produce a "final" Version from within VScode (consider, that I have not set up a CI Pipeline yet)?

Kind regards.

carsten-doctor wrote

I am a little bit confused

IT IS confusing at the beginning don't worry, it's part of the learning process.
No one is going to be bothered, just ask.

carsten-doctor wrote

Is it just syntax highlighting and the preview tool?

In short, yes. AsciiDoctor makes a disctintion between:
* API: libraries to run Asciidoctor embedded in other tools. This is what is being used by cli, previewers, and build tools.
* CLI(s): used for single doc conversion from terminal. For example the Ruby CLI (https://docs.asciidoctor.org/asciidoctor/latest/get-started/). All CLIs are compatible, so you can choose whatever you are more familiar with Ruby, JavaScript or Java.
* Preview tools: like vscode, or Intellij plugin. This are becoming amazingly advanced (specialy the intellij) but the use case of preview is not the same and they use certain options to optimize it that create different results.
* Build tools: similar to cli but for more complex scenarios, like agregating multiple sources. Here we have things like the maven & gradle plugins, gulp, or just custom scripts.

At the beginning is nice to have an editor to generate the output but as soon as you start adding things (multiple sources, multiple outputs, ...) you'll find yourself moving to cli and build tools.

If you are looking for a nice WYSIWYG experience with good conversion options to begin, I'd look at https://asciidocfx.com/.

carsten-doctor wrote

Will output ("AsciiDoc: Save/Export .... ") still be generated through the preview module or will these commands (used from VScode command palette) call the CLI?

I pressume (I am not the mantainer of that tool) it uses the JavaScript API to convert the document. In theory you can replicate 100% the CLI, but for the use case of the preview it must be using some optimizations and that's why things are slighly different.

carsten-doctor wrote

How should I produce a "final" Version from within VScode (consider, that I have not set up a CI Pipeline yet)?

Deppends on what you are doing. Seems to be a simple single page doc.
Just install whatever cli you preffer (Ruby, JavaScript or Java) and run "COMMAND file.adoc". Being Windows, I highly recommend using WSDL. Or if you don't want to install anything, there's also the docker image https://github.com/asciidoctor/docker-asciidoctor.
Also, if you plan on using VSCode, once the system is setup, you can create tasks to make things easier https://code.visualstudio.com/docs/editor/tasks.

abelsromero wrote

carsten-doctor wrote

Will output ("AsciiDoc: Save/Export .... ") still be generated through the preview module or will these commands (used from VScode command palette) call the CLI?

I pressume (I am not the mantainer of that tool) it uses the JavaScript API to convert the document. In theory you can replicate 100% the CLI, but for the use case of the preview it must be using some optimizations and that's why things are slighly different.

Maybe someone can assist? What gets installed with the plugin - see also next paragraph.

abelsromero wrote

Deppends on what you are doing. Seems to be a simple single page doc.
Just install whatever cli you preffer (Ruby, JavaScript or Java) and run "COMMAND file.adoc". Being Windows, I highly recommend using WSDL. Or if you don't want to install anything, there's also the docker image https://github.com/asciidoctor/docker-asciidoctor.
Also, if you plan on using VSCode, once the system is setup, you can create tasks to make things easier https://code.visualstudio.com/docs/editor/tasks.

After installing the plugin in VScode, can I already build a VScode task or do I have to download and install a standalone CLI for asciidoc/asciidoctor? Where are the binaries located, which must be called...extension dir of VScode, I presume.

I'm not sure that I understand how WSDL fits in this picture.

I suspect you assume the VSCode runs some scripts/binaries under the hood and that's not it, it's pure JavaScript.
To make a proper conversion, you will need to install a CLI separated from VSCode.

To make things simple, I'd suggest to ignore most of what I said and start simple.

* With VSCode you can edit, no problem about that. But the preview has some limitations.
* To convert a document without limitations, I'd sugest the Ruby CLI. No need to know Ruby, is just a command. Here are the details https://docs.asciidoctor.org/asciidoctor/latest/install/windows/. The section below shows how to use the basic command https://docs.asciidoctor.org/asciidoctor/latest/get-started/.

I must correct myself, I found out it's possible to use a cli to generate the preview.
Under the plugin settings you can disable the use of asciidoctor_js and instead use a "command", with that it is possible to inject all options to get a good preview. Sitll with the vscode theme applied to it, so not 100% the same.

Many thnx up to this point!

As you might have guessed, I'm a "noob in it all". ;-)

After installing ruby and the asciidoctor gem I can produce HTML output where {docname} gets replaced by the file's name. This all by just running asciidoctor name-of-file.adoc.

Alas, disabling asciidoctor.js is all i can do in VScode, there is no command I can put instead. Doing so, in preview I still get shown {docname}.

Maybe you can assist a little further....

No luck, I setup the command and still showing {docname} because it redirects input to command under-the-hood.


Still, about the config, if you were able to get to the Extension settins panel, there's a search bar at the top containing "@ext:asciidoctor.asciidoctor-vscode", replace with "@ext:asciidoctor.asciidoctor-vscode command" and the option should be more obvious.
It only contains "asciidoctor" as value and requires the cli to be available in PATH. To test it's working, try typing something else like "asciidoctorx" and you will get an error in the preview panel showing the command it's running under the hood.

I created an issue to discuss the feature https://github.com/asciidoctor/asciidoctor-vscode/issues/412.