## ascaid
Hassle-free documentation generation powered by AsciiDoc
### TL;DR
⚡️ Write documents in [AsciiDoc](https://asciidoctor.org) format
⚡️ Include text-based diagrams in your documents:
⚡️ Extend AsciiDoc with custom extensions:
⚡️ Publish your documents to Confluence and code hosting services
### Longer Description
**ascaid** makes it easy to write partially-generated documentation in AsciiDoc format. Generating the documentation can help with reducing [documentation CRUFT](http://agilemodeling.com/essays/agileDocumentation.htm).
Under the hood, **ascaid** uses [Asciidoctor.js](https://docs.asciidoctor.org/asciidoctor.js/latest) and [Pandoc](https://pandoc.org) and offers the following main features:
- It can be configured to load [Asciidoctor.js Extensions](https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/ecosystem)
- It includes a live server to help with writing AsciiDoc documents
- It can convert Asciidoc files to [GitHub Flavored Markdown](https://github.github.com/gfm)
- It can publish GitHub Flavored Markdown files to [Confluence](https://www.atlassian.com/software/confluence)
The following diagram shows a typical document writing and publishing workflow with **ascaid**.
*Note: This document is generated with* ***ascaid*** *itself.* *Check out the source [here](https://github.com/fardjad/node-ascaid/blob/master/adocs/README.adoc).*
### Installation
#### Requirements
1. A Unix-like operating system ([WSL](https://docs.microsoft.com/en-us/windows/wsl) is also supported)
2. [Bash](https://www.gnu.org/software/bash)
3. [Node.js](https://nodejs.org)
4. [Pandoc](https://pandoc.org)
You can install the package globally with npm:
npm install -g ascaid
### CLI Usage
#### `ascaid help`
Usage: ascaid [options] [command]
Hassle-free documentation generation powered by AsciiDoc
Options:
-V, --version output the version number
-h, --help display help for command
Commands:
serve [directory] start an AsciiDoc server
adoc-to-gfm AsciiDoc -> GitHub flavored markdown
gfm-to-confluence Publish a GitHub flavored markdown directory to
Confluence
help [command] display help for command
#### `ascaid serve`
Usage: ascaid-serve [options] [rootDir]
Start an AsciiDoc server
Arguments:
rootDir server root directory (default: current
directory)
Options:
-V, --version output the version number
-c, --config config file path
-a, --attribute [key=value...] set a document attribute. The value given will
override values from the config file. Passing
the key without =value will unset the
attribute (default: [])
-h, --help display help for command
#### `ascaid adoc-to-gfm`
Usage: ascaid-adoc-to-gfm [options]
Recursively convert AsciiDoc files in a directory to GitHub flavored markdown
Arguments:
srcDir source directory
outDir output directory
Options:
-V, --version output the version number
--ignore [globPattern...] glob patterns to ignore (default: ["**/_*"])
-c, --config config file path
-a, --attribute [key=value...] set a document attribute. The value given will
override values from the config file. Passing
the key without =value will unset the
attribute (default: [])
-h, --help display help for command
#### `ascaid gfm-to-confluence`
Usage: ascaid-gfm-to-confluence [options]
Recursively publish a GitHub flavored markdown directory to Confluence
Arguments:
dir dir to publish to Confluence
Options:
-V, --version output the version number
--api-base-url [apiBaseUrl] Confluence API base URL
--api-username [apiUsername] Confluence API username
--api-password [apiPassword] Confluence API password
--space-key [spaceKey] Confluence space key
--root-page-id [rootPageId] Confluence root page ID
--root-page-title [rootPageTitle] Confluence root page title
-h, --help display help for command
### Config File
You can optionally use a config file to register custom extensions and set [Asciidoctor.js](https://docs.asciidoctor.org/asciidoctor.js/latest) options. On startup, **ascaid** looks for a config file named `ascaid.config.json` or `ascaid.config.jsonc` in the current working directory. The following block shows an example config file:
``` highlight
{
// JSON comments will be striped out
"$schema": "https://raw.githubusercontent.com/fardjad/node-ascaid/master/ascaid.config.schema.json",
"extensions": [
// npm i asciidoctor-kroki
"asciidoctor-kroki",
"./path/to/extension.js"
],
// https://docs.asciidoctor.org/asciidoctor/latest/api/options/
"asciidoctorOptions": {
// https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref/
"attributes": {
"nofooter": true,
"kroki-server-url": "http://my-server-url:port"
}
}
}
```
### Extensions
**ascaid** supports [Asciidoctor.js Extensions](https://docs.asciidoctor.org/asciidoctor.js/latest/extend/extensions/ecosystem).
An example implementation of a custom extension can be found [here](https://github.com/fardjad/node-ascaid/blob/master/examples/asciidoctor-extension).
### Publishing Documents to Confluence
In order to publish [AsciiDoc](https://asciidoctor.org) documents to [Confluence](https://www.atlassian.com/software/confluence), you should first convert them to [GitHub Flavored Markdown](https://github.github.com/gfm) (see [CLI Usage](#_cli_usage) for more info). Then you’ll need to create an [API token](https://id.atlassian.com/manage/api-tokens) and a root page to publish the documents under. An example project with GitHub Actions integration can be found [here](https://github.com/fardjad/node-ascaid/blob/master/examples/github-actions-publish-to-confluence).