# Evolving AsciiDoc into a Specification > [! note]- > The content of this page is generated by audio/video transcription and text transformation from the content and links of this source. Source: [https://fosdem.org/2025/schedule/event/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/](https://fosdem.org/2025/schedule/event/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/) <video src="https://video.fosdem.org/2025/k4201/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem.av1.webm" controls></video> ## Summary & Highlights: The session titled 'Evolving real-world AsciiDoc into a specification and how it will help the ecosystem' at FOSDEM 2025, presented by Alexander Schwartz, focuses on the evolution of AsciiDoc into a formal specification. This development is crucial for standardizing documentation practices across open-source projects, enhancing both contributor and user experiences. Schwartz discusses the current AsciiDoc tools and the challenges they face, emphasizing the need for a unified language specification to ensure consistent parsing and rendering across different tools and platforms. The session also highlights the role of the Eclipse Foundation in managing AsciiDoc's brand and language documentation. **Introduction to AsciiDoc and Its Importance** AsciiDoc is a plain text markup language widely used in open-source projects for writing technical content. Its popularity stems from its rich feature set and ability to modularize and reuse content, making it a preferred choice for many developers and documentarians. **Challenges in Documentation Pipelines** Integrating various parts of a documentation pipeline can be challenging. AsciiDoc's evolving specification aims to address these challenges by providing standard parsing rules, which will help streamline the authoring, verification, conversion, and publishing processes. **The Role of the Eclipse Foundation** The AsciiDoc Working Group at the Eclipse Foundation is spearheading efforts to publish the AsciiDoc Language documentation and develop the AsciiDoc Language Specification. This initiative is crucial for establishing a standardized approach to AsciiDoc parsing and rendering. **Tools and Workflows in AsciiDoc** The session showcases various AsciiDoc tools and workflows used in real-world project documentation pipelines. These tools facilitate writing, validating, reviewing, and publishing documentation, offering features like syntax highlighting, auto-completion, and grammar checks. **The Future of AsciiDoc** The development of the AsciiDoc Language Specification promises to solve existing challenges by ensuring that different tools and implementations parse AsciiDoc consistently. This will enhance the overall user experience and foster greater collaboration within the open-source community. ## Importance for an eco-social transformation AsciiDoc's evolution into a formal specification is significant for eco-social transformation as it promotes open-source collaboration and knowledge sharing. By standardizing documentation practices, it enables more efficient and accessible dissemination of information, which is vital for sustainable development. Eco-social designers can leverage AsciiDoc's tools and workflows to create and share documentation that supports environmental and social initiatives. Challenges include ensuring broad adoption of the specification and overcoming technical barriers in integrating AsciiDoc into diverse project environments. ## Slides: | | | | --- | --- | | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_001.jpg\|300]] | The first slide introduces the session titled 'Evolving real-world AsciiDoc® into a specification and how it will help the ecosystem,' presented by Alexander Schwartz, Principal Software Engineer at Red Hat. It sets the stage for the discussion on the transformation of AsciiDoc into a formal specification and its impact on the documentation ecosystem. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_002.jpg\|300]] | The second slide outlines the mission of the session: to get documentation to readers effectively. It highlights the workflow of authoring, converting, and publishing, and introduces the AsciiDoc Brand and Language Documentation, as well as the AsciiDoc Language Specification. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_003.jpg\|300]] | The third slide reiterates the mission to deliver documentation to readers and emphasizes the workflow of authoring, converting, and publishing. It also mentions the AsciiDoc Brand and Language Documentation and the ongoing development of the AsciiDoc Language Specification. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_004.jpg\|300]] | The fourth slide focuses on the mission to get documentation to readers. It underscores the need for authors to concentrate on content and structure, conversion processes that support multiple targets from a single source, and the importance of published documentation in educating users and providing answers. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_005.jpg\|300]] | The fifth slide reinforces the mission to deliver documentation to readers and details the workflow of authoring, converting, and publishing. It also introduces the AsciiDoc Brand and Language Documentation and the AsciiDoc Language Specification. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_006.jpg\|300]] | The sixth slide discusses the authoring process, emphasizing the importance of writing, validating, and reviewing documentation. It compares different tools like editors, IDEs, browsers, and CLI for authoring. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_007.jpg\|300]] | The seventh slide highlights the advantages of writing in an IDE, such as distraction-free writing, syntax highlighting, autocompletion, and grammar and style checks, which enhance the authoring experience. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_008.jpg\|300]] | The eighth slide elaborates on writing in an IDE, focusing on the ability to scroll and navigate context, view styled previews, and collaborate using version control, all of which contribute to a seamless documentation workflow. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_009.jpg\|300]] | The ninth slide explains how to structure text and lists in AsciiDoc. It suggests putting each sentence on a separate line, using blank lines to create new paragraphs, and employing bold and italic text for emphasis. It also covers the use of lists with dots and asterisks. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_010.jpg\|300]] | The tenth slide describes how to use paragraphs and admonitions in AsciiDoc. It explains marking paragraphs as important, using shorter one-line syntax for tips, and providing examples in example blocks. It also covers syntax highlighting for listings. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_011.jpg\|300]] | The eleventh slide explains how to create tables in AsciiDoc. It details the use of `|===` to mark the beginning and end of tables, the syntax for table titles and columns, and how to format table cells with AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_012.jpg\|300]] | The twelfth slide discusses embedding source code in AsciiDoc. It covers standard includes for Java code, using icons for callouts, and selecting specific lines from source files to include in documentation. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_013.jpg\|300]] | The thirteenth slide focuses on validating documentation content using tools like Vale. It provides an example configuration for Vale and explains how to integrate it with GitHub pull requests for content validation. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_014.jpg\|300]] | The fourteenth slide discusses conversion tools for AsciiDoc, comparing different build tools like Maven, npm, and CLI. It also compares various output formats such as HTML, PDF, and DocBook, and highlights different AsciiDoc implementations. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_015.jpg\|300]] | The fifteenth slide contrasts command line converters with embedded tools for AsciiDoc. It provides an example of using Asciidoctor to convert files and highlights the importance of handling warnings and errors during conversion. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_016.jpg\|300]] | The sixteenth slide discusses writing extensions for AsciiDoc that interact on a structural level. It explains how extensions can add new macros, manipulate documents on an AST level, and generate content for multiple output formats. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_017.jpg\|300]] | The seventeenth slide focuses on publishing AsciiDoc content using tools like Antora. It highlights Antora's capabilities for static site publishing, generating websites, and automating the publishing process. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_018.jpg\|300]] | The eighteenth slide distinguishes between AsciiDoc as a language and Asciidoctor as an implementation. It emphasizes Asciidoctor's role in static site publishing and its features for generating websites and customizing themes. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_019.jpg\|300]] | The nineteenth slide continues to differentiate AsciiDoc from Asciidoctor, highlighting Asciidoctor's features for static site publishing, customizable themes, navigation outlines, and site search capabilities. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_020.jpg\|300]] | The twentieth slide further elaborates on Asciidoctor's features, including page outlines, custom navigation, page linking, and redirects for renamed pages, enhancing the user experience for published documentation. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_021.jpg\|300]] | The twenty-first slide outlines the roles and responsibilities in using Antora for publishing. It covers the author's role in creating content, the Docu Ops role in preparing automation scripts, and the web developer's role in customizing themes. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_022.jpg\|300]] | The twenty-second slide summarizes the session's mission, workflow, and focus on AsciiDoc Brand and Language Documentation, as well as the AsciiDoc Language Specification. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_023.jpg\|300]] | The twenty-third slide provides information on AsciiDoc's brand and language documentation, managed by the Eclipse Foundation. It invites attendees to reach out to the AsciiDoc Working Group for brand-related inquiries. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_024.jpg\|300]] | The twenty-fourth slide directs attendees to the AsciiDoc website for more information about the language and resources, emphasizing the importance of brand and language documentation. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_025.jpg\|300]] | The twenty-fifth slide encourages attendees to visit the AsciiDoc language documentation website to learn more about the language, highlighting the significance of brand and language documentation. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_026.jpg\|300]] | The twenty-sixth slide reiterates the session's mission and workflow, emphasizing the importance of the AsciiDoc Brand and Language Documentation and the ongoing development of the AsciiDoc Language Specification. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_027.jpg\|300]] | The twenty-seventh slide invites attendees to get involved with the AsciiDoc Language Specification project on GitLab and participate in discussions on the AsciiDoc chat platform. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_028.jpg\|300]] | The twenty-eighth slide discusses Specification Decision Records, which are used to agree on the AsciiDoc specification. It emphasizes the community's role in standardizing behavior in a backward-compatible way. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_029.jpg\|300]] | The twenty-ninth slide introduces the Technology Compatibility Kit (TCK) for checking implementation compatibility with the AsciiDoc specification. It provides an example of how document structures are represented in JSON for testing. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_030.jpg\|300]] | The thirtieth slide provides links to resources related to AsciiDoc, Asciidoctor, and the IntelliJ AsciiDoc Plugin. It also includes links to videos, slides, and examples for further learning. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_031.jpg\|300]] | The thirty-first slide provides contact information for Alexander Schwartz, including his email, personal website, and social media handles, encouraging attendees to connect with him for further discussion. ## Links [Slides](https://fosdem.org/2025/events/attachments/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/slides/237905/2025-02-0_nWAZ3O6.pdf) [Video recording (MP4)](https://video.fosdem.org/2025/k4201/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem.av1.mp4) [Video recording (AV1/WebM)](https://video.fosdem.org/2025/k4201/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem.av1.webm) [Chat room (web)](https://fosdem.org/2025/chat/k4201) [Chat room (app)](https://fosdem.org/2025/chat/app/k4201)