| = Tools for Working with AsciiDoc Files |
| // Licensed to the Apache Software Foundation (ASF) under one |
| // or more contributor license agreements. See the NOTICE file |
| // distributed with this work for additional information |
| // regarding copyright ownership. The ASF licenses this file |
| // to you 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. |
| |
| == AsciiDoc vs Asciidoctor |
| |
| The Solr Ref Guide is written in _AsciiDoc_ format. This format is generally considered an extension of Markdown, because it has support for tables of contents, better table support, and other features that make it more appropriate for writing technical documentation. |
| |
| We are using a version of the AsciiDoc syntax along with tools from an open source project called https://asciidoctor.org[Asciidoctor]. This provides full support for the AsciiDoc syntax, but replaces the original Python processor with one written in Ruby. There is a Java implementation, known as https://github.com/asciidoctor/asciidoctorj[AsciidoctorJ]. Further extensions from the original AsciiDoc project include support for font-based icons and UI elements. |
| |
| == Helpful Tools |
| |
| You can write AsciiDoc without any special tools. It's simply text, with familiar syntax for bold (`*`) and italics (`_`). |
| |
| Having some tools in your editor is helpful, though. |
| |
| === Doc Preview |
| |
| This allows you to see your document in something close to what it might appear like when output to HTML. |
| |
| The following information is from http://asciidoctor.org/docs/editing-asciidoc-with-live-preview. |
| |
| * Atom has AsciiDoc Preview, which gives you a panel that updates as you type. There are also a couple of other plugins to support AsciiDoc format and auto-complete. |
| * There is a Live Preview browser plugin for Chrome, Firefox and Opera which allow you to open your AsciiDoc page in the browser. It will also update as you type. |
| * There is also an Intellij IDEA plugin to support AsciiDoc format. |
