/asciidocular

Mobile first HTML5 web app for your project documentation written in AsciiDoc

Primary LanguageCSSApache License 2.0Apache-2.0

Asciidocular

Build Status

Note
 Currently highly under development.

Asciidocular is a small AngularJS web app that loads AsciiDoctor files via Ajax and renders them as a full web site. Asciidocular uses asciidoctor.js to convert the AsciiDoc files into HTML.

Asciidocular can be used to create a documentation site of your project or API. For example, you could use Asciidocular together with Swagger2Markup to create a documentation site of your Swagger API.

Since AsciiDoc syntax is just plain text, you can write an AsciiDoc document using any text editor.

Advantages:

  • No build process and server-side tools needed to convert your AsciiDoc files into HTML

  • Responsive Bootswatch (Bootstrap) theme

  • Deployable via GitHub Pages

  • Just create AsciiDoc files and deploy!

Features:

  • Supports highlight.js

  • Supports Font-Awesome

Demo

Live Demo deployed on GitHub Pages.

Usage Guide

Building from source

Make sure you have Node.js installed.

git clone https://github.com/RobWin/asciidocular.git
cd asciidocular
npm run build

Create AsciiDoc files

You have to create an index.adoc file in the docs folder of the app.

= Asciidocular //(1)
Robert Winkler
:icons: font
:icons: font
:source-highlighter: highlightjs
:hardbreaks:
:idprefix:

This is a preamble. (2)

[icon="fa fa-wrench"] (3)
== Chapter 1 //(4)

=== Chapter 1.1 //(5)

Text in chapter 1.1

* Item 1
* Item 2

NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!

\include::chapter2.adoc[] //(6)

  1. The document title is the title of the web site.

  2. The preamble of the document is the content of the jumbotron.

  3. You can add Font Awesome icons in front of top-level navigation items

  4. Each level 1 section title is a top-level navigation item

  5. Each level 2 section title is a sub navigation item of the parent section in the navigation bar.

  6. You can include other AsciiDoc files into the index.adoc file.

Examples

Asciidocular on Mobile Phone

asciidocular mobile

Asciidocular on Tablet

Home

asciidocular home

Sections

asciidocular section

Questions

You can ask questions about Asciidocular in Gitter.

Bugs

If you believe you have found a bug, please take a moment to search the existing issues. If no one else has reported the problem, please open a new issue that describes the problem in detail and, ideally, includes a test that reproduces it.

Enhancements

If you’d like an enhancement to be made to Asciidocular, pull requests are most welcome. The source code is on GitHub. You may want to search the existing issues and pull requests to see if the enhancement is already being worked on. You may also want to open a new issue to discuss a possible enhancement before work on it begins.

License

Copyright 2015 Robert Winkler

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.