I write most of my documentation with Asciidoctor, so saving some keystrokes is important. You can add window=_blank to links in your Asciidoctor source. For example: * https://www.duckduckgo.com[window=_blank] * https://www.duckduckgo.com[DuckDuckGo, window=_blank] https://www.duckduckgo.com DuckDuckGo So this creates links with the html source: <ul> <li> <p><a href="https://www.duckduckgo.com" class="bare" target="_blank" rel="noopener">https://www.duckduckgo.com</a></p> </li> <li> <p><a href="https://www.duckduckgo.com" target="_blank" rel="noopener">DuckDuckGo</a></p> </li> </ul> The good thing is, that there is a shortcut for this. You can replace window=_blank with a ^: * https://www.duckduckgo.com[^] * https://www.duckduckgo.com[DuckDuckGo^] https://www.duckduckgo.com DuckDuckGo

Read more

Asciidoctor for Professional Looking Documentation

For GPN19 I prepared a second talk on Documentation with any Editor. The talk was based on a previous one from Froscon 13, but the pipeline tooling changed. This time there was a technical issue during the recording and so there are only the slides available, but you can still watch the video of the Froscon talk: Froscon 13: Documentation with any Editor All scripts and the complete pipeline definition can be found in the GPN19-documentation Gitlab Repository. tl;dr I use Asciidoctor for documentation for years. It’s just easy to write, has more options than Markdown and I create all kinds of output for colleagues, customers or the web, just from one source.

During my talk at FrOSCon I wasn’t sure how to install Asciidoctor on Windows. So I tried on a Windows 10 VM. When you want to use Asciidoctor on a Windows desktop, you need to download the Rubyinstaller and install it. Now you can open a administrative command window and install with gem install asciidoctor. Let’s test with an easy document: test.adoc = Test Asciidoctor on Windows :icons: font == Admonition NOTE: Will this work? TIP: Convert with `asciidoctor test.adoc` Update I had a typo in the conversion command, you can still see it in the screenshot.

Read more

Today I attended Froscon 13 in St. Augustin. Froscon is one or the biggest event around Opensource in Germany. Thanks again to organizers sponsors of this awesome event, it was a pleisure to be here and have the chance to give a talk. The slides for my session "Documentation with any editor" can be found at https://gitlab.com/stoeps/froscon18-presentation/blob/master/froscon13-documentationwithanyeditor.pdf. If you’re interested and missed the talk, there is a video recording at https://media.ccc.de available. Example files linked from session slides are stored in this Gitlab Repostitory https://gitlab.com/stoeps/asciidoctor-documentation-example, here you find the used build.gradle, Makefile and CI/CD configuration I normally use.

Read more