4 ms·
No Asciidoc? I know (and use daily) the IntelliJ Asciidoc plugin, so it's surprising to me that they make a writing plugin/environment and don't support AD out
by mikro2nd 3y ago
No Asciidoc? I know (and use daily) the IntelliJ Asciidoc plugin, so it's surprising to me that they make a writing plugin/environment and don't support AD out of the box.
eta: Having now had a closer look, some more thoughts:
The tool is clearly focussed on writing docs "for a website"; for external consumption. (For whatever value you choose for "external".) Definitely not for internal-to-a-project docs that you'd want side-by-side in a code project[1]. So no wikilinking between pages, which is (for me) a deal-breaker, making this thing basically just a previewing Markdown editor that also does XML source.
Well, it's early days, so let's hope that the tool becomes all it might be someday. But if you're doing "for external consumption via a website" docs, then maybe this can be useful to you, though it's hard to see what it's doing that a dozen other previewing Markdown editors don't already do, and some better.
[1] Yes, I'm aware that there are several plugins to IJ that do side-by-side note-making in projects. I've tried (probably) all of them, and they're all badly deficient in one way or another.
- janosdebugs 3y agoThis. Any time I saw a more complex doc work with several editors and reviewers, it was in Asciidoc.
- byb 3y agoI want to second your comment. AsciiDoc is growing in popularity. A year ago I surveyed a dozen tools and went all in with it. I'd like to see IJ take it a step further beyond AsciiDoc, by supporting Antora to generate and deploy static websites. When combined with Antora-Assembler its also possible to generate PDFs using the ruby-based AsciiDoctor PDF. I'm currently introducing a Docs-as-Code workflow using Visual Studio Code at my organization, because of the very permissive license terms of VSC and the decent AsciiDoc preview function. Mostly though, I find reading adoc files quite easy until lots of Antora snippets (which don't resolve) and conditions start getting added in. A lot of technical writers I've met have had a hard time understanding XML, which is nothing to say of the average office worker who wants to open up their old copy of Office 97 and write a completely unstructed document with a WYSIWIG interface. IJ IDE licenses start to add up, so if IJ is competitive against Oxygen, this might make sense for a lot of organizations to jump over.
- jddj 3y agoDoes the asciidoc to pdf workflow involve an intermediate html / headless chromium step?
- byb 3y agoIn most cases no, AsciiDoctor-PDF converter uses the Ruby library PDF library Prawn to generate PDFs, However, there are alternative PDF converters which do convert from HTML (the VSC AsciiDoctor plug-in allows the option to use a different converter), but I don't think they use chrome. Please note that using different pdf converters is a bit of an advanced topic. https://wkhtmltopdf.org/ https://wkhtmltopdf.org/, and asciidoctor-web-pdf. https://github.com/ggrossetie/asciidoctor-web-pdf https://github.com/ggrossetie/asciidoctor-web-pdf I encourage everyone to take a look at the documentation; this is the markup language I now use for all my personal and professional projects. https://docs.asciidoctor.org/ https://docs.asciidoctor.org/
- tacker2000 3y agoI used the asciidoctor/asciidoctor-pdf program extensively a while ago, and whilst it wasn’t that bad, it was still a bit hacky, didnt support page breaks for example. But maybe it got better now…
- bobbylarrybobby 3y agoThe docs call out that page break is supposed to work in PDF, so I guess it should work now? I've found Asciidoctor-pdf to be pretty incredible in the output it produces — only problem is the arcane config file…