asciidoctor-documentation 0

General documentation for the AsciiDoc syntax, the Asciidoctor processor and various projects in the Asciidoctor ecosystem

= Asciidoctor Documentation :infra-ref: :templates-ref: :readme-repo: :issue-docs: :homepage: :sources: :issues: :forum: :org:

CAUTION: The information and processes in this README are being brainstormed and discussed. They have not been implemented!

But speaking of brainstorming, we’re looking for people to add some thunder and lightning!

Do you have ideas about how to:

  • automate documentation so code and references stay up-to-date?
  • flag and tag documents according to versions?
  • link source code to documents across repositories?
  • outline and structure user-friendly manuals?
  • write, edit, automate, deploy, etc. documentation?

If so, don’t hesitate to file an issue, start a wikipage, fork this repo, or join the discussion link pending on the mailing list.

== Overview

The Asciidoctor Documentation project’s goal is to build, store, and distribute the content relevant to the Asciidoctor organization and its projects.

This repository will store and maintain the:

  • General documentation guidelines
  • General document building instructions
  • Asciidoctor Organization documents (such as the {infra-ref}[Infrastructure Goals and Planning] document)
  • {templates-ref}[Content guides and templates] for writing READMEs, changelogs, manuals, tutorials, etc.
  • Source code for building documents that include content from multiple repositories
  • Writer’s guide
  • General contributor manual
  • General developer guidelines
  • FAQ
  • Tutorials (which will be released to the website)
  • Additional learning materials (presentations, etc.) that are cross-repository
  • Project collateral

Additionally, the Asciidoctor Documentation repository will distribute each project’s documentation for publication on the Asciidoctor website. It will build additional and alternate forms of documentation from content and code flagged and included throughout the repositories.

== Asciidoctor Documentation repository structure

The asciidoctor-documentation directory contains:

  • {readme-repo}[README]
  • {infra-ref}[Infrastructure Goals and Planning]
  • {templates-ref}[/templates directory] ** {templates-ref}/readme-template.adoc[README guide and template] ** {templates-ref}/release-notes-template.adoc[Release Notes guide and template] ** {templates-ref}/tutorial-template.adoc[Tutorial guide and template] ** {templates-ref}/user-manual-template.adoc[User Manual guide and template]

[horizontal] README:: Purpose and description of the Asciidoctor Documentation project

Infrastructure Goals and Planning:: Planning document outlining information, suggestions, and questions about building the Asciidoctor organization’s infrastructure.

Templates directory:: Location of the content guides and templates for writing READMEs, changelogs, manuals, tutorials, etc.

README guide and template:: Style and structure suggestions for a project’s README.

Release notes guide and template:: Style and structure suggestions for a project’s release notes.

Tutorial guide and template:: Style and structure suggestions for a project’s tutorials.

User manual guide and template:: Style and structure suggestions for a project’s user manual.

NOTE: Many more guides and templates are planned, checkout the ideas and requests filed in the {issue-docs}[issue tracker] for more information.

== Documentation for Asciidoctor core and other Asciidoctor organization projects

Each project within the Asciidoctor organization and Asciidoctor core will store and maintain its own:

  • Installation and usage quick start
  • User manual
  • Technical manual
  • Syntax and code dictionary
  • Changelog
  • License
  • Specific contribution instructions

The core repository will also store and maintain the:

  • Syntax writing quick start

== Contributing instructions


=== Issues

Use this repository’s issue tracker to file issues and feature requests regarding the goals of this repository and its documents.

== Build instructions

See {infra-ref}[Infrastructure Goals and Planning] for more information.

// == Copyright and licensing information

// == Author(s)

// == Thanks, acknowledgments, and credits

== General Asciidoctor Contact and help information

Project home page:: {homepage}

Core source code repository:: {sources}

Core issue tracker:: {issues}

Mailing list / forum:: {forum}

GitHub organization:: {org}

//// == Bugs

  • List of known bugs
  • Instructions on reporting new bugs

== Changelog ////

Related Repositories



A Leiningen plugin for generating documentation using Asciidoctor ...



BDD living documentation using Cucumber and Asciidoctor ...



Control how your asciidoctor powered documentation looks ...



This is a Swagger2Markup Gradle template project which uses the swagger2markup-gradle-plugin to convert a contract-first Swagger specification into an AsciiDoctor-based HTML documentation. ...



This is a Swagger2Markup Maven template project which uses the swagger2markup-maven-plugin to convert a contract-first Swagger specification into an AsciiDoctor-based HTML documentation. ...

Top Contributors