Asciidoctor
One day to contribute to Open Source!
Guillaume Grossetie
Hack commit push 2021
29th May 2021
What’s Asciidoctor
Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc® markup into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats.
= Hello, AsciiDoc!
Doc Writer <doc@example.com>
An introduction to http://asciidoc.org[AsciiDoc].
== First Section
* item 1
* item 2
[source,ruby]
puts "Hello, World!"
Ecosystem
Asciidoctor also has an ecosystem of extensions, converters, build plugins, and tools to help you author and publish content written in AsciiDoc.
In addition to running on Ruby, Asciidoctor can be executed on a JVM using AsciidoctorJ or in any JavaScript environment using Asciidoctor.js.
Quick overview
Asciidoctor Converters
Asciidoctor has built-in converters for HTML, DocBook 5 and manual pages.
In addition, the Asciidoctor community provides add-on converters for PDF, EPUB3, reveal.js, and more...
Asciidoctor Extensions
Extensions are central to the success of AsciiDoc because they open up the language to new use cases.
Asciidoctor provides an extension API that offers a superset of extension points. As a result, extensions in Asciidoctor are easy to write, powerful, and simple to distribute.
Asciidoctor Tooling
The Asciidoctor community (and beyond) provides a variety of build tool integrations, and tooling plugins to make it easier to work with AsciiDoc.
Asciidoctor.js
AsciidoctorJ
Contributing!
Contributing
New contributors are always welcome!
If you discover errors or omissions in the source code, documentation, or website content, please don’t hesitate to submit an issue or open a pull request with a fix.
How to contribute
Here are some ways you can contribute
Issues and new features
Issues label as “good first”, “hackfest” or “help wanted” are up for grabs!
If the description is unclear, or if you need help to find the right issue, feel free to ask!
Prerequisite knowledge
Contributing to Asciidoctor requires some experience with a lightweight markup language such as Markdown or AsciiDoc.
This is not strictly required but it will help you to get started.
JavaScript devs
Good first issues for JavaScript devs
The Command Line Interface (CLI) for Asciidoctor.js, built with Yargs.
Good first issues for JavaScript devs
Render AsciiDoc (.ad, .adoc, .asc, .asciidoc) files as HTML inside Chrome (Chromium), Firefox, Edge, and Opera!
Built using the WebExtensions API.
Good first issues for JavaScript devs
An extension for Asciidoctor.js to convert diagrams to images using Kroki!
Having some knowledge about Kroki is a plus
Good first issues for TypeScript devs
A VS Code extension that provides live preview, syntax highlighting, and snippets for the AsciiDoc format using Asciidoctor!
Having some knowledge about VS Code extensions is a plus
Java devs
Good first issues for Java devs
Convert AsciiDoc documents using Asciidoctor during an Apache Maven build.
Requires some knowledge about Maven
Good first issues for Java devs
A plugin for the IntelliJ platform (IntelliJ IDEA, RubyMine, etc.) that provides support for the AsciiDoc markup language.
Having some knowledge about the Intellij platform is a plus
Ruby devs
Good first issues for Ruby devs
An extension for Asciidoctor.js to convert diagrams to images using Kroki!
Having some knowledge about Kroki is a plus
Good first issues for Ruby devs
Good first issues for Ruby devs
A converter for Asciidoctor that transforms an AsciiDoc document into an HTML5 presentation designed to be executed by the reveal.js presentation framework.
Having some knowledge about reveal.js is a plus
Docs
Documentation
The Asciidoctor project recently migrated its documentation from Awestruct to Antora
Though, we still need to migrate some content to complete the migration and could use some help!
Good first issues for doc writers
Links
Asciidoctor Converters
Asciidoctor Extensions
Tooling
Asciidoctor core
Contribute to Asciidoctor core (Ruby)
Contributing to Asciidoctor core requires a strong knowledge about AsciiDoc and is “reserved” for experienced Ruby developers.
The code is highly optimized and a lot of people are using it, so each change is thoroughly reviewed.
Contribute to Asciidoctor core (Ruby)
As Asciidoctor is built using Ruby, some basic knowledge of Ruby, RubyGems and Minitest is beneficial. The following resources provide a good starting point for contributors who may not be completely comfortable with these tools:
While these resources don't cover everything needed, they serve as a good starting off point for beginners.
https://github.com/asciidoctor/asciidoctor/blob/master/CONTRIBUTING.adoc