asciidoctor-intellij-plugin
asciidoctor-intellij-plugin copied to clipboard
asciidoctor
Should support Hugo
Hugo is one of the most popular open-source static site generators, it should be supported.
I write the post in WebStorm, but the images can not find the directory.
Thanks for raising this request. In order to support a specific directory layout there should be some marker that (like a pom.xml marks a Maven project, or a antora.yml that marks an Antora component).
I assume you refer to a project like https://github.com/diguage/www.diguage.com. I'm not familiar with Hugo, and I don't see a marker file there.
As an alternative, there is a generic mechanism in the plugin to provide hints about images to the AsciiDoc plugin: the .asciidoctorconfig file: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/asciidoctorconfig-file.html
Usually this is solved by adding an imagesdir to the .asciidoctorconfig file if the images are relative. Looking at the repository above, those targets start with /, thereby they are absolute.
One way to solve that could have been introducing an attribute plus an ifdef::env-idea[] as described here https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/conditional-rendering.html possibly in each blog post.
As an alternative I updated the image resolving for the preview in the plugin; it now uses the imagesdir for the preview even when image targets start with a /.
To try this out, install the latest pre-release 0.37.40 of the AsciiDoc plugin. Then add a file like the following in the root of the project:
// .asciidoctorconfig in the root of the project
:imagesdir: {asciidoctorconfigdir}/static
This will then show as follows in the editor and in the preview. You'll also notice that auto-completion works for the images in the editor.
Please give it a try and let me know how this works for you.
The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.
I tested the config file:
// .asciidoctorconfig in the root of the project
:imagesdir: {asciidoctorconfigdir}/static
It did not work well for me.
WebStorm 2022.2
Build #WS-222.3345.108, built on July 23, 2022
Runtime version: 17.0.3+7-b469.32 x86_64
VM: OpenJDK 64-Bit Server VM by JetBrains s.r.o.
macOS 10.15.7
GC: G1 Young Generation, G1 Old Generation
Memory: 2048M
Cores: 12
Metal Rendering is ON
Non-Bundled Plugins:
PlantUML integration (5.16.1)
org.asciidoctor.intellij.asciidoc (0.37.36)
As described above, please update to pre-release 0.37.40 first. It will not work with earlier releases.
Hugo does not have marker.
# Clone the hugo site
$ git clone [email protected]:diguage/www.diguage.com.git
# clone the theme
$ git submodule update --init --recursive
# Set up the hugo
$ hugo server
# Then you can access the site throuth: http://localhost:1313/
### another way
# Build the site in product model
$ hugo --minify
# Then the build site in the public folder,
$ cd public
$ python -m http.server 8000 # Python3
# Then you can access the site throuth: http://localhost:8000/
The config file of Hugo is in config folder, config/_default is used in hugo server and config/production is used in hugo --minify。
╭─☞ /path/to/www.diguage.com git:(master)
╰─➜ $ tree
.
├── LICENSE
├── README.adoc
├── archetypes
│ └── default.adoc
├── config $ Config folder
│ ├── _default
│ │ └── config.toml $ Be used in `hugo server`
│ └── production
│ └── config.toml $ Be used in `hugo --minify`
├── content
│ ├── about.adoc
│ ├── archives.adoc
│ └── post $ the articles
│ └── asciidoc-vs-markdown.adoc
├── resources
│ └── _gen
│ ├── assets
│ └── images
├── static
│ ├── ads.txt
│ ├── css
│ │ ├── asciidoctor.css
│ │ ├── rouge-github.css
│ │ └── rouge-monokai.css
│ └── images $ images folder, be used as `image::/images/website/hugo-logo.svg[]`
│ ├── avatar.jpg
│ ├── website
│ │ ├── asciidoc.png
│ │ ├── hugo-logo.svg
│ │ ├── markdown.png
│ │ └── wordpress.png
│ └── wireframes
│ └── best-architecture.png
└── themes
└── mainroad $ the theme folder
The build file tree
╭─☞ /path/to/www.diguage.com/public git:(master)
╰─➜ $ tree
.
├── 404.html
├── about
│ └── index.html
├── ads.txt
├── apple-touch-icon.png
├── archives
│ └── index.html
├── categories
│ ├── index.html
│ ├── index.xml
│ ├── java
│ │ ├── index.html
│ │ ├── index.xml
│ │ └── page
│ │ ├── 1
│ │ │ └── index.html
│ │ └── 2
│ │ └── index.html
│ └── 阅读摘要
│ ├── index.html
│ ├── index.xml
│ └── page
│ ├── 1
│ │ └── index.html
│ └── 2
│ └── index.html
├── css
│ ├── asciidoctor.css
│ ├── rouge-github.css
│ ├── rouge-monokai.css
│ └── style.min.css
├── favicon.ico
├── images $ The images
│ ├── alipay.png
│ ├── avatar.jpg
│ ├── website
│ │ ├── antora.png
│ │ ├── asciidoc-plantuml.png
│ │ ├── asciidoc-seqdiag.png
│ │ ├── asciidoc.png
│ │ ├── asciidoctor-diagram-kroki-cheatsheet.jpeg
│ │ ├── hugo-logo.png
│ │ ├── hugo-logo.svg
│ │ ├── markdown-vs-asciidoc-catalog.png
│ │ ├── markdown-vs-asciidoc.jpg
│ │ ├── markdown.png
│ │ ├── optimize.jpg
│ │ └── wordpress.png
│ ├── wireframes
│ │ └── best-architecture.png
│ ├── wx-jikerizhi-qrcode.jpg
│ ├── wx-jikerizhi.jpg
│ ├── wxpay.jpg
│ └── wxpay.png
├── index.html
├── index.xml
├── js
│ └── menu.js
├── page
│ ├── 1
│ │ └── index.html
│ └── 8
│ └── index.html
├── post $ The converted articles
│ └── asciidoc-vs-markdown
│ └── index.html
├── sitemap.xml
└── tags
├── shell
│ ├── index.html
│ ├── index.xml
│ └── page
│ └── 1
│ └── index.html
├── tcp
│ ├── index.html
│ ├── index.xml
│ └── page
│ └── 1
│ └── index.html
└── udp
├── index.html
├── index.xml
└── page
└── 1
└── index.html
@ahus1 Maybe it helps you.
As described above, please update to pre-release 0.37.40 first. It will not work with earlier releases.
The 0.37.40 is OK.
If I set the :imagesdir: {asciidoctorconfigdir}/static in .asciidoctorconfig, the images are displayed in the preview window. and if I remove the option, the images are not found.
It is better to hide the config in the plugin. If the plugin finds that the project is a Hugo project and the AsciiDoc files are found, then set the config option.
All in all, this is an awesome plugin. Thank you, @ahus1
Thanks for trying this.
I'd be happy to add some automatic rules for Hugo, and for that I would need to know more about Hugo:
- the config folder can also be a config.toml file AFAIK
- will the folder static have always the same name independent of the theme or config being used?
I don't need a single marker file, it could also be more complex rules - they only need to be specific and reliable. Can you please help me here? Thanks!
It's my pleasure.
- The config folder is fixed, and the config file is one of
config.toml,config.yamlorconfig.json. - The folders are always the same regardless of theme.
The document:
There is now pre-release 0.37.41 that automatically detects Hugo. The docs describe how the detection works, and how images in static can be referenced: https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/hugo.html - it also mentions how page resources work, so that they are closer to the blog post and not in the /static folder.
The .asciidoctorconfig file is no longer necessary for the images. Still, it can help you to use the same CSS from the site for the preview; see the link at the end of the Hugo documentation page for details.
Please install the preview and let me know how this works for you. Support for other Hugo features might be added over time.
The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.
I tested the plugin, it is OK.
I read the https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/hugo.html , there is an error.
// show a global resource with an absolute target
image::/static/images/image-in-static.png[] # the path is wrong.
↓
image::/images/image-in-static.png[] # the path is right.
Thanks for taking the time to test and review it. I fixed the docs.
Closing this issue. If you find any other feature that is missing for Hugo, please open another issue.