This repository/project facilitates planning for and participation in Asciidoctor-related “programming” at Write the Docs 2019. Asciidoctor is an official sponsor of Writing Day 2019 (Sunday, 19 May), but all of the activities discussed here are officially part of WTD 2019.
We are a group of AsciiDoc aficionados/evangelists eager to share our open-source ways with everyone who loves creating great technical documentation. These are some ways we hope to enhance the WTD 2019 experience for ourselves and other participants.
WTD Conference Presence
Writing Day
Asciidoctor is a proud sponsor of WTD Writing Day 2019. As a nonprofit open-source provider, Asciidoctor will have a strong presence throughout the conference. On Writing Day, volunteers will offer tutorials and workshops on common sticking points, from setting up an environment to working with Git to deploying a site sourced in AsciiDoc and generated by Antora or Jekyll. Writing Day Activities are being planned under the writing day and session issues tags.
Lightning Talks
We should not nominate more than one Asciidoctor-specific Lightning talk, if that; and we should accept that the committee might reject it on the basis that it might look like favoritism. But we certainly have learned countless lessons in our years doing docs-as-code that are not exactly “on-brand”.
Recommendations for 5-minute, general-audience lessons go under the Lightning Talks Brainstorm issue.
Unconference Sessions
These are 30-minute roundtables, usually very informal. They can give a topic a deep dive, involving discussion or demos. There’s no telling how many people will show up, but we can print up some logo-emblazoned cards to make them stand out.
Suggestions for and discussion of Unconference session topics goes under the unconference and session labels.
This Repository/Project
This GitHub project (DocOps/wtd2019) hosts the origin repository for Asciidoctor’s presence at WTD.
It also builds a demonstration website with content contributed by participants through a GitHub-based workflow.
This is an example project consisting of numerous components and lots of code. It took one person about five hours to set up. You are welcome to duplicate it and modify it for your own purposes.
Platforms, Tools, & Dependencies
Here is all the totally free, open-source software you will need to engage with this repository.
Source Control
Asciidoctor does not require a source control system, and it works with any source-control system. Nevertheless, it should always be used in conjunction with Git.
Rendering Environment
In order to transform AsciiDoc files to HTML, this project uses a Ruby-based Asciidoctor toolchain, including the Jekyll static-site generator with Asciidoctor’s jekyll-asciidoc plugin.
These tools, in turn, rely on a Ruby runtime environment, which you must have installed to build the site locally.
Ruby on MacOS or Linux
If you’re on Linux or MacOS, you probably have Ruby runtime.
Using your preferred terminal application, check your Ruby version with ruby -v.
Asciidoctor works on a huge range of Ruby versions, but Jekyll currently requires at least version 2.4.0.
Use your OS’s package manager (homebrew, apt-get, yum, dpkg, etc) to upgrade Ruby if needed.
Ruby on Windows
If you’re on Windows, you need a proper Bash terminal emulator as well as Ruby runtime. You have probably already installed GitBash, so now you must Download the very latest version with DevKit. WTDer Anne Gentle has provided excellent instructions for getting up and running on Windows with Ruby and Jekyll. (There are some good MacOS tips there as well.)
Editing/Writing
AsciiDoc markup can be edited using any application that handles plain text.
The cross-platform editor with the most complete support and easiest installation process is Atom.
Install it, then install the package AsciiDoc Assistant (menu:Preferences[+ Install] and search for asciidoc).
Deployment
The origin repository is on GitHub, and draft previews are built and deployed using Netlify, which also hosts the published version at https://writetheasciidocs.netlify.com/.
Alternative Tools
If you don’t like AsciiDoc, take a look at reStructuredText.
Lots of people are picky about text/code editors. If Atom is not to your liking, consider any number of alternative editors with AsciiDoc integration, including AsciidocFX.
There are lots of alternatives to Jekyll for generating docs websites. Check out this list of static site generators with AsciiDoc support and the broader list of SSGs.
Netlify is an outstanding deployment platform, but if you want to keep everything on GitHub, you can. GitHub Pages can serve any static website. You can also deploy to Amazon AWS S3 or any webserver anywhere.
Contributions & Workflow
We intend to offer this repo and GitHub project space as a playground for the whole WTD2019/Asciidoctor experience. Participants in our Writing Day programming will be able to branch or fork this repo and issue merge requests with new content.
Meta
Asciidoctor’s presence at Write the Docs is an ad-hoc project.
Who We Are
This project was kicked off by members of the teams behind Asciidoctor, Antora, and LiquiDoc — fully open-source tools intended to make the AsciiDoc markup language more powerful and accessible. If you want to get involved, let us know how!
Beyond WTD2019
This repository can be “versioned” to incorporate future events, as well. Our generated website could have a version switcher, versioned search, and so forth.
License
This repository is maintained collaboratively by OpenDevise, Codewriting, and other contributors, released like the rest of our toolchain, under The MIT License.