Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Evolving real-world AsciiDoc into a specificati...

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.

Alexander Schwartz PRO

February 01, 2025

Transcript

32 slides
  1. TM Evolving real-world AsciiDoc® into a specification and how it

    will help the ecosystem Alexander Schwartz, Principal Software Engineer @ Red Hat FOSDEM Tool the Docs Developer Room | Brussels, BE | 2025-02-01
  2. Evolving real-world AsciiDoc into a specification 1 Mission: Get the

    docs out to the readers! 2 Workflow: Author, Convert, Publish 3 AsciiDoc Brand and Language Documentation 4 AsciiDoc Language Specification CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 2
  3. Evolving real-world AsciiDoc into a specification 1 Mission: Get the

    docs out to the readers! 2 Workflow: Author, Convert, Publish 3 AsciiDoc Brand and Language Documentation 4 AsciiDoc Language Specification CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 3
  4. Mission Get the docs out to the readers! • 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 CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Publish 4
  5. Evolving real-world AsciiDoc into a specification 1 Mission: Get the

    docs out to the readers! 2 Workflow: Author, Convert, Publish 3 AsciiDoc Brand and Language Documentation 4 AsciiDoc Language Specification CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 5
  6. Author, Convert, Publish Author Write Editor vs. IDE Validate vs.

    Browser vs. Review CLI CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 6
  7. Author, Convert, Publish Writing in an IDE • Write without

    distraction • Syntax highlighting • Autocompletion • Grammar and style check CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 7
  8. Author, Convert, Publish Writing in an IDE • Scrolling and

    the context navigate • Styled Preview • Collaborate using version control CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 8
  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. CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 9
  10. Author, Convert, Publish Paragraphs and Admonitions [IMPORTANT] -You can mark

    a paragraph to be important. -TIP: There is also the shorter one-linesyntax. ==== 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. ---- CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 10
  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 |=== CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 11
  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 CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 12
  13. Author, Convert, Publish Validating the contents # .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 CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 13
  14. Author, Convert, Publish Convert HTML Maven Asciidoctor (Ruby, JavaScript, Java)

    vs. vs. PDF npm vs. vs. vs. DocBook CLI libasciidoc (Go) vs. vs. … … vs. Asciidoc - hs (Haskell) vs. … CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 14
  15. Author, Convert, Publish Command line converters vs. embedding $ asciidoctor

    test.adoc asciidoctor: WARNING: test.adoc: line 2: multiple ids detected in style attribute CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 15
  16. Author, Convert, Publish Extensions to interact on structural level 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 • … CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 16
  17. Author, Convert, Publish Publish Antora CC BY-NC-SA 4.0 | February

    2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 17
  18. AsciiDoc ist die Sprache, Asciidoctor ist eine Implementierung CC BY-NC-SA

    4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 18
  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 CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 19
  20. • • • • AsciiDoc ist die Sprache, Asciidoctor ist

    eine Implementierung Page outline Custom Navigation Page linking Redirects when pages have been renamed CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 20
  21. Author, Convert, Publish Antora: Roles and responsibilities 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 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/ CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 21
  22. Mission Get the docs out to the readers! • 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 CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz Publish 22
  23. Evolving real-world AsciiDoc into a specification 1 Mission: Get the

    docs out to the readers! 2 Workflow: Author, Convert, Publish 3 AsciiDoc Brand and Language Documentation 4 AsciiDoc Language Specification CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 23
  24. Brand and Language Documentation AsciiDoc Brand AsciiDoc® and AsciiDoc Language

    Inc. are trademarks of the Eclipse Foundation, For questions related to these brand guidelines please reach out to the AsciiDoc Working Group. https://www.eclipse.org/org/artwork/guidelines/asciidoc-brand-guidelines.pdf CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 24
  25. Brand and Language Documentation AsciiDoc Website Visit https://asciidoc.org/ to learn

    about AsciiDoc and links to all resources. CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 25
  26. Brand and Language Documentation AsciiDoc Language Documentation Visit https://docs.asciidoctor.org/asciidoc/latest/ CC

    BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz to learn about the language. 26
  27. Evolving real-world AsciiDoc into a specification 1 Mission: Get the

    docs out to the readers! 2 Workflow: Author, Convert, Publish 3 AsciiDoc Brand and Language Documentation 4 AsciiDoc Language Specification CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 27
  28. Brand and Language Documentation AsciiDoc Language Specification Visit https://gitlab.eclipse.org/eclipse/asciidoc at

    https://chat.asciidoc.org/ CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz - lang to get involved, and discuss 28
  29. Brand and Language Documentation Specification Decision Records to agree on

    a spec Community and experts agree on how to standardize the behavior in a best backwards compatible way. CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 29
  30. Brand and Language Documentation TCK to check compatibility of implemenations

    = 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 }] }, ... CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 30
  31. Links AsciiDoc https://asciidoc.org Asciidoctor https://asciidoctor.org 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 Slides: IntelliJ AsciiDoc Plugin https://ahus1.de/post/technical - writing - udemy @[email protected] @[email protected] CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz @ahus1.de @ahus1.de 31
  32. Contact Alexander Schwartz Principal Software Engineer [email protected] https://www.ahus1.de @ahus1.de @[email protected]

    CC BY-NC-SA 4.0 | February 2025 | Evolving real-world AsciiDoc® into a specification | Alexander Schwartz 32

More Decks by Alexander Schwartz

Other Decks in Technology