Documentation Architecture

What is the Docs Repo?

The Docs Repo will be where all of the compiled documentation relating to the Asciidoctor organization will be stored. It will also be where documentation that is not packaged with individual repositories will be stored.

How does it operate?

The Docs repo will consist of files that will be linked to the docs and source code in individual repos. These files will update automatically when changes are made to linked docs and/or code in individual repositories. Publication sources will then pull from the Docs repository for content (ex. the documentation displayed on the project’s main website.

What does each repository need to provide?

1. /docs folder

2. README

3. Reference Doc that contains definitions and working usage examples of all attributes, options, styles, configurations

4. Quickstart which contains requirements, installation, configuration and basic usage instructions with examples

5. API reference documentation

6. Changelogs

7. branch solely for updating the documentation

8. Code examples are to be pulled directly from the source code or test suite

README Template

1. What the project does

2. Whom it’s for

3. Operating systems and/or platforms it runs on

4. Any dependencies and requirements

5. How to install it, or a pointer to in-depth directions

6. Links to help and contact info

7. License

Write it for someone who has never heard of your project. Define terms and acronym. Link to more complete docs, tutorials, how-to materials.

Reference Documentation Template

Contains definitions and working usage examples of all attributes, options, styles, configurations

Quickstart Guide

Contains requirements, installation, configuration and basic usage instructions with examples

Documentation Webpage Topic flow (aka the navigation)

Getting started

• Introductions

  • Hello! If you’re here…​

  • What is Asciidoctor?

• Key features

  • Compare to MarkDown

  • Compare to AsciiDoc

• Quick-start and output guide

• Installation

• Requirements

  • Terminal

• Install the Gem

  • Extensions and Options

• Commandline Usage

  • Basic Commands

  • from --help

• API Usage

  • Basic Commands

• Output formats

• Text Editor

Write your Content

• Document anatomy

• Header, Title and Author

• Text and Paragraphs

  • Preventing Substitutions

• Sections

• Lists

• Tables

• Blocks

• Admonitions

• Links and Cross references

• Images and Videos

• Document Attributes

• Sourcecode highlighting

• Callouts and Icons

• Footnotes

• TOC

• Metadata

Stylesheets and Outputs

• Default stylesheet and backend

• Stylesheet factory

• Custom stylesheets

• DocBook

• Slideshows

  • Deck.js

• Custom backends

• Previewing a document

Publishing

• Locally

• Multipart books and large documents

• GitHub

• Awestruct

• Blogdiggitty

Enriching the output

• Attributes and Chunks

• Chunking content and metadata

• Includes

• Font Icons

• Images dir

• Section links

Converting to Asciidoctor

Markdown

Build Integrations and Implementations

• Java

• Gradle

• Maven

• JavaDoc

• Javascript

• Yard

• Rdoc

Community

• Getting Help

• Contributing

  • Content

  • Code

• Issues and Requests

• Roadmap

• History

Resources

• A Short Manual of Nearly Everything Asciidoctor

• API Doc

• Presentations, Screencasts and Videos

• Asciidoctor in Use