Evolving real-world AsciiDoc into a specification and how it will help the ecosystem

Lots of open-source projects use documentation as code to collaborate on web sites and documentation. But how do you integrate the different parts of a documentation pipeline to provide a great contributor and user experience?

AsciiDoc is a popular plain text markup language for writing technical content, and lots of open-source projects use it. It’s loved for its rich features and its ability to modularize and reuse content. The AsciiDoc Working Group at the Eclipse Foundation has recently published the AsciiDoc Language documentation, and it is continuing to work on the AsciiDoc Language Specification that is the foundation to define standard parsing rules for the language.

This talk showcases different AsciiDoc tools in real-world project documentation pipelines to show what is possible today when you author, verify, convert, and publish content. It also highlights what challenges will be solved with the evolving AsciiDoc Language Specification.

Transcript

1. Evolving real-world AsciiDoc® into a specification and how it will help the ecosystem Alexander Schwartz, Principal Software Engineer @ Red Hat OCX Conference | Mainz, DE | 2024-10-24 TM
2. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 2 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4
3. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 3 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4
4. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 4 Get the docs out to the readers! Mission • Authors should focus on content and its structure • Conversion should support multiple targets from a single source • Published documentation educates users and provides answers to their questions Author Convert Publish
5. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 5 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4
6. 6 Author Author, Convert, Publish Write Validate Review CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Editor vs. IDE vs. Browser vs. CLI
7. 7 Writing in an IDE Author, Convert, Publish CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz • Write without distraction • Syntax highlighting • Autocompletion • Grammar and style check
8. 8 Writing in an IDE Author, Convert, Publish CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz • Scrolling and navigate the context • Styled Preview • Collaborate using version control
9. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 9 Author, Convert, Publish Texts and lists Each sentence should be in a separate line. Every blank line creates a new paragraph. You can write *bold* text. _Italic_ works as well text. Lists . work . with . dots to make them numbered and * asterisks * to * make bullet points.
10. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 10 Author, Convert, Publish Paragraphs and Admonitions [IMPORTANT] -- You can mark a paragraph to be important. -- TIP: There is also the shorter one-line- syntax. ==== This is an example block. Use it to provide examples to your users. ==== ---- This is a listing. You can provide syntax highlighting for XML/Java etc. here. ----
11. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 11 Author, Convert, Publish Tables Tables are blocks, `|===` marks their beginning and end. .Table title [cols="1,1,3a,1"] |=== |H1 |H2 |H3 |H4 |Cell 1 |Cell 2 |Formatting *of words* works like in _before_ if you switch the column or cell to AsciiDoc format. |Cell 4 |===
12. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 12 Author, Convert, Publish Embedding Source Code .Standard include [,java] ---- include::Example.java[] ---- :icons: font .Pick a block with callout [,java,indent=0] ---- include::Example.java[tag=sop] ---- <1> this is your first line of Java
13. 13 Validating the contents Author, Convert, Publish CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz # .vale.ini StylesPath = .github/styles MinAlertLevel = suggestion Packages = RedHat IgnoredClasses = error-message [*.adoc] BasedOnStyles = RedHat RedHat.TermsErrors = warning https://github.com/errata-ai/vale-action
14. 14 Convert Author, Convert, Publish CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Maven vs. npm vs. CLI vs. … HTML vs. PDF vs. DocBook vs. … Asciidoctor (Ruby, JavaScript, Java) vs. libasciidoc (Go) vs. Asciidoc-hs (Haskell) vs. …
15. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 15 Command line converters vs. embedding Author, Convert, Publish $ asciidoctor test.adoc asciidoctor: WARNING: test.adoc: line 2: multiple ids detected in style attribute
16. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 16 Extensions to interact on structural level Author, Convert, Publish Write extensions that • Extend the AsciiDoc syntax by adding new macros • Interact with a document on an AST level • Generate AsciiDoc content that can be rendered in any supported output format • …
17. 17 Publish Author, Convert, Publish CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Antora
18. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 18 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung
19. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 19 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung • Static site publishing for AsciiDoc content • Generates a simple to host website • Fully automated publishing • Customizable Theme to match your design • Navigation outline • Site Search
20. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 20 AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung • Page outline • Custom Navigation • Page linking • Redirects when pages have been renamed
21. Author: • Creates content in a well-defined folder structure • Customizes navigation and versions Docu Ops: • Prepares automation scripts for validation and publishing Web Developer: • Customizes the UI theme CC BY-NC-SA 4.0 | April 2024 | Documentation for users​ with AsciiDoc and Antora | Alexander Schwartz 21 Antora: Roles and responsibilities Author, Convert, Publish my-component ├─ antora.yml └─ modules ├─ ROOT │ ├─ attachments │ ├─ examples │ ├─ images │ ├─ pages │ │ └─ index.adoc │ ├─ partials │ └─ nav.adoc └─ a-named-module └─ pages Quick Start Guide: https://docs.antora.org/antora/3.1/install-and-run-quickstart/
22. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 22 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4
23. AsciiDoc® and AsciiDoc Language are trademarks of the Eclipse Foundation, Inc. For questions related to these brand guidelines please reach out to the AsciiDoc Working Group. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 23 AsciiDoc Brand Brand and Language Documentation https://www.eclipse.org/org/artwork/guidelines/asciidoc-brand-guidelines.pdf
24. Visit https://asciidoc.org/ to learn about AsciiDoc and links to all resources. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 24 AsciiDoc Website Brand and Language Documentation
25. Visit https://docs.asciidoctor.org/asciidoc/latest/ to learn about the language. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 25 AsciiDoc Language Documentation Brand and Language Documentation
26. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 26 Evolving real-world AsciiDoc into a specification Mission: Get the docs out to the readers! 1 Workflow: Author, Convert, Publish 2 AsciiDoc Brand and Language Documentation 3 AsciiDoc Language Specification 4
27. Visit https://gitlab.eclipse.org/eclipse/asciidoc-lang to get involved, and discuss at https://chat.asciidoc.org/ CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 27 AsciiDoc Language Specification Brand and Language Documentation
28. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 28 Specification Decision Records to agree on a spec Brand and Language Documentation Community and experts agree on how to standardize the behavior in a best backwards compatible way.
29. CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 29 TCK to check compatibility of implemenations Brand and Language Documentation = Document Title body { "name": "document", "type": "block", "attributes": {}, "header": { "title": [ { "name": "text", "type": "string", "value": "Document Title", "location": [{ "line": 1, "col": 3 }, { "line": 1, "col": 16 }] } ], "location": [{ "line": 1, "col": 1 }, { "line": 1, "col": 16 }] }, ...
30. AsciiDoc https://asciidoc.org Asciidoctor https://asciidoctor.org IntelliJ AsciiDoc Plugin https://ahus1.de/post/technical-writing-udemy Links CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 30 @ahus1de @ahus1de Antora https://antora.org/ https://www.ahus1.de/post/documentation-site-antora Videos, slides and examples https://www.ahus1.de/post/asciidoctor-intro-and-deep-dive @ahus1@fosstodon.org @ahus1@fosstodon.org
31. Contact Alexander Schwartz Principal Software Engineer alexander.schwartz@gmx.net https://www.ahus1.de @ahus1de @ahus1@fosstodon.org CC BY-NC-SA 4.0 | October 2024 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 31