diff --git a/docs/asciidoctor-docker.adoc b/docs/asciidoctor-docker.adoc new file mode 100644 index 000000000..6abefdce0 --- /dev/null +++ b/docs/asciidoctor-docker.adoc @@ -0,0 +1,3 @@ +:page-layout: base + +include::https://cdn.rawgit.com/asciidoctor/docker-asciidoctor/master/README.adoc[] diff --git a/docs/developer-guide.adoc b/docs/developer-guide.adoc new file mode 100644 index 000000000..685c6d13f --- /dev/null +++ b/docs/developer-guide.adoc @@ -0,0 +1,50 @@ += Developer Guide +:page-layout: base + +== Implementations + +[cols="1,3a"] +|=== +| image:http://placehold.it/150x100&text=Ruby[] +| +[unstyled] +* API +* Parser +* AST +* link:/rdoc/Asciidoctor.html[Rdoc] +* link:/man/asciidoctor/[+asciidoctor+ man page] +* Yard +* Doctest Suite +* html-pipeline (infrastructure for GitHub) +| image:http://placehold.it/150x100&text=Java[] +| +[unstyled] +* link:../asciidoctorj/[API] +* http://www.javadoc.io/doc/org.asciidoctor/asciidoctorj/1.5.4[Javadoc] +* https://github.com/asciidoctor/asciidoclet[Asciidoclet] + +| image:http://placehold.it/150x100&text=JavaScript[] +| +[unstyled] +* API +* webjars +* Browser +* Node +* Opal +| image:http://placehold.it/150x100&text=Groovy[] +| +[unstyled] +* https://github.com/asciidoctor/asciidoctorj-groovy-dsl[DSL] +|=== + +== Plugins + +* link:../asciidoctor-gradle-plugin/[Gradle] +* link:../asciidoctor-maven-plugin/[Maven] +* https://github.com/asciidoctor/asciidoctor-gulp-plugin[Gulp] +* https://github.com/asciidoctor/asciidoctor-grunt-plugin[Grunt] +* https://github.com/asciidoctor/asciidoctor-lein-plugin[Leiningen] +* https://github.com/asciidoctor/asciidoctor-ant[Ant] +* https://github.com/ktoso/asciidoctor-sbt-plugin[sbt] +* https://github.com/asciidoctor/asciidoctor-intellij-plugin[Intellij] +* Eclipse (in progress) diff --git a/docs/extensions.adoc b/docs/extensions.adoc deleted file mode 100644 index 5ec0996bf..000000000 --- a/docs/extensions.adoc +++ /dev/null @@ -1,73 +0,0 @@ -= List of Asciidoctor Extensions -:page-layout: docs -:sectanchors: -:icons: font -ifndef::env-site[] -:toc: left -:idprefix: -:idseparator: - -endif::[] - -This page is a catalog of Asciidoctor extensions. -In this context, an extension is a library that enriches the AsciiDoc content either by introducing new syntax or weaving additional features into the output. -This differs from tool extensions, such as the Atom extension, which bring AsciiDoc support to the tool. - -== Official Extensions - -[cols="1,0,5"] -|==== -|Name |Runtime |Description - -|http://asciidoctor.org/docs/asciidoctor-diagram[Asciidoctor Diagram] -|Asciidoctor -|A set of extensions for Asciidoctor that allow you to embed diagrams written using the PlantUML, Graphviz, ditaa, or Shaape syntax inside your AsciiDoc documents. - -|https://github.com/asciidoctor/asciidoctor-latex[Asciidoctor LaTeX] -|Asciidoctor -|Makes it possible to convert AsciiDoc documents into LaTeX and HTML. -It also brings an extended mathematical syntax for the AsciiDoc markup language that closely parallels LaTeX. - -|https://github.com/asciidoctor/asciidoctor-extensions-lab[Extension Lab] -|Asciidoctor -|An experimental playground for upcoming extensions. -Used to test the capabilities of the extension mechanism and new extension ideas. - -|==== - -NOTE: The label “official” simply means that the extension is hosted inside the Asciidoctor organization on GitHub and is maintained as part of the Asciidoctor project. -In contrast, a third-party extension is one hosted outside of the Asciidoctor organization. -This classification does not indicate the quality of the extension. -Instead, the quality should be based on the extension's own merit. - -== Third-party Extensions - -[cols="1,0,5"] -|==== -|Name |Runtime |Description - -|https://github.com/domgold/asciidoctor-gherkin-extension[Asciidoctor Gherkin] -|AsciidoctorJ -|Includes Gherkin feature files in AsciiDoc in the form of sections, paragraphs, lists and tables. - -|http://fix.github.io/asciidoctor-screenshot[Asciidoctor Screenshot] -|AsciidoctorJ -|Automates the inclusion of dynamically-generated screenshots into your documentation. - -|https://github.com/RobWin/markup-document-builder[Markup Document Builder] -|AsciidoctorJ -|This project is a document builder for markup documents, including AsciiDoc. - -|https://github.com/allati/asciidoctor-extension-monotree[MonoTree] -|AsciidoctorJ -|Visualizes tree-like structures. -It takes names for a tree node and it's nesting level as an input and draws a tree as an output. - -|https://github.com/domgold/asciidoctor-sdedit-extension[Asciidoctor sdedit] -|AsciidoctorJ -|Creates sequence diagrams using sdedit. - -|https://github.com/rmpestano/cukedoctor[Cukedoctor] -|AsciidoctorJ -|Enables BDD living documentation by integrating Cucumber and Asciidoctor. - -|==== diff --git a/docs/getting-started.adoc b/docs/getting-started.adoc new file mode 100644 index 000000000..3c6390a83 --- /dev/null +++ b/docs/getting-started.adoc @@ -0,0 +1,131 @@ += Get Started with Asciidoctor +:page-layout: base +:uri-asciidoctor-org: https://github.com/asciidoctor + +Let's setup and use the Asciidoctor toolchain! + +== Installation + +[unstyled] + * image:linux-logo.svg[Linux, 50, 50, link="../install-toolchain/"] link:../install-toolchain/[Linux] + * image:macosx-logo.svg[Mac OSX, 50, 50, link="../install-asciidoctor-macosx/"] link:../install-asciidoctor-macosx/[Mac OSX] +// TODO Add a dedicated guide to install Asciidoctor on Windows +// * image:windows-logo.svg[Windows, 50, 50, link="../install-windows/"] link:../install-windows/[Windows] + * image:docker-logo.svg[Docker, 50, 50, link="../asciidoctor-docker/"] link:../asciidoctor-docker/[Docker container] + +== Viewing Tools + + * http://gist.asciidoctor.org/[Docgist] + * link:../editing-asciidoc-with-live-preview/#chrome[Chrome Extension] + * link:../editing-asciidoc-with-live-preview/#firefox[Firefox Addon] + * link:../editing-asciidoc-with-live-preview/#opera[Opera Extension] + * link:../editing-asciidoc-with-live-preview/#using-a-system-monitor[Guard with Live Reload] + +== Editing Tools + + * link:../editing-asciidoc-with-live-preview/#atom[Atom] + * link:../editing-asciidoc-with-live-preview/#brackets[Brackets] + * link:../editing-asciidoc-with-live-preview/#asciidocfx[AsciiDocFX] + +== Web Publishing + + * http://hubpress.io/[HubPress.io] + * https://www.gitbook.com/[GitBook.io] (supports AsciiDoc) + * {uri-asciidoctor-org}/asciidoctor-confluence[Confluence] + * {uri-asciidoctor-org}/jekyll-asciidoc[Jekyll] + * https://github.com/opendevise/editions[Editions] + * https://middlemanapp.com/[Middleman] + * http://awestruct.org/[Awestruct] + +== Converters + +NOTE: You should first read link:../render-documents/[How-to render a document] to understand how Asciidoctor produces output formats. + + * link:../render-documents/#rendering-a-document-to-html[HTML] + * link:../render-documents/#rendering-a-document-to-docbook[DocBook] + * link:../user-manual/#man-pages[Manpages] + * link:../convert-asciidoc-to-pdf/[PDF] + * link:../convert-asciidoc-to-epub[EPUB] + * http://www.noteshare.io/section/asciidoctor-latex-manual-intro[Latex] + * link:../install-and-use-deckjs-backend/[Deck.js] + * link:../install-and-use-revealjs-backend/[Reveal.js] + * link:../produce-custom-themes-using-asciidoctor-stylesheet-factory/[Stylesheets] + * DZSlides + * XHTML + * fopub (archived) + * Custom styles per converter + +== Diagrams and Equations + + * link:../asciidoctor-diagram/[PlantUML] + * link:../asciidoctor-diagram/[Ditaa] + * link:../asciidoctor-diagram/[GraphViz DOT] + * Shaape + * BlockDiag, SeqDiag, ActDiag, NwDiag + * Salt + +== Extensions + +This section is a catalog of Asciidoctor extensions. +In this context, an extension is a library that enriches the AsciiDoc content either by introducing new syntax or weaving additional features into the output. +This differs from tool extensions, such as the Atom extension, which bring AsciiDoc support to the tool. + +=== Official Extensions + +[cols="1,0,5"] +|==== +|Name |Runtime |Description + +|http://asciidoctor.org/docs/asciidoctor-diagram[Asciidoctor Diagram] +|Asciidoctor +|A set of extensions for Asciidoctor that allow you to embed diagrams written using the PlantUML, Graphviz, ditaa, or Shaape syntax inside your AsciiDoc documents. + +|https://github.com/asciidoctor/asciidoctor-latex[Asciidoctor LaTeX] +|Asciidoctor +|Makes it possible to convert AsciiDoc documents into LaTeX and HTML. +It also brings an extended mathematical syntax for the AsciiDoc markup language that closely parallels LaTeX. + +|https://github.com/asciidoctor/asciidoctor-extensions-lab[Extension Lab] +|Asciidoctor +|An experimental playground for upcoming extensions. +Used to test the capabilities of the extension mechanism and new extension ideas. + +|==== + +NOTE: The label “official” simply means that the extension is hosted inside the Asciidoctor organization on GitHub and is maintained as part of the Asciidoctor project. +In contrast, a third-party extension is one hosted outside of the Asciidoctor organization. +This classification does not indicate the quality of the extension. +Instead, the quality should be based on the extension's own merit. + +=== Third-party Extensions + +[cols="1,0,5"] +|==== +|Name |Runtime |Description + +|https://github.com/domgold/asciidoctor-gherkin-extension[Asciidoctor Gherkin] +|AsciidoctorJ +|Includes Gherkin feature files in AsciiDoc in the form of sections, paragraphs, lists and tables. + +|http://fix.github.io/asciidoctor-screenshot[Asciidoctor Screenshot] +|AsciidoctorJ +|Automates the inclusion of dynamically-generated screenshots into your documentation. + +|https://github.com/RobWin/markup-document-builder[Markup Document Builder] +|AsciidoctorJ +|This project is a document builder for markup documents, including AsciiDoc. + +|https://github.com/allati/asciidoctor-extension-monotree[MonoTree] +|AsciidoctorJ +|Visualizes tree-like structures. +It takes names for a tree node and it's nesting level as an input and draws a tree as an output. + +|https://github.com/domgold/asciidoctor-sdedit-extension[Asciidoctor sdedit] +|AsciidoctorJ +|Creates sequence diagrams using sdedit. + +|https://github.com/rmpestano/cukedoctor[Cukedoctor] +|AsciidoctorJ +|Enables BDD living documentation by integrating Cucumber and Asciidoctor. + +|==== diff --git a/docs/hack-asciidoctor-maven-plugin.adoc b/docs/hack-asciidoctor-maven-plugin.adoc deleted file mode 100644 index 35dfd8356..000000000 --- a/docs/hack-asciidoctor-maven-plugin.adoc +++ /dev/null @@ -1,51 +0,0 @@ -= Hacking on the Asciidoctor Maven Plugin -Jason Porter -:page-layout: docs -ifndef::env-site[:toc: left] -:repo-ref: http://github.com/asciidoctor/asciidoctor-maven-plugin -:issues-ref: http://github.com/asciidoctor/asciidoctor-maven-plugin/issues -:discuss-ref: http://discuss.asciidoctor.org -:asciidoc-ref: http://asciidoc.org -:maven-ref: http://maven.apache.org -:docs-ref: link:/docs -:maven-guide-ref: link:/docs/install-and-use-asciidoctor-maven-plugin -:spock-ref: http://spockframework.org - -The {repo-ref}[Asciidoctor Maven plugin] is the official means of using Asciidoctor to render your {asciidoc-ref}[AsciiDoc] documentation using {maven-ref}[Apache Maven]. -This guide teaches you how to hack on it. - -For help running this plugin, review the {maven-guide-ref}[How do I install and use the Asciidoctor Maven plugin guide]. - -== Hacking - -Developer setup for hacking on this project isn't difficult. -The requirements are: - -* Java -* Maven 3 - -All the other dependencies will be brought in by Maven. -You should be able to use IntelliJ, Eclipse, or Netbeans without any issue for hacking on the project. - -== Building - -Standard Maven build: - - $ mvn clean install - -== Testing - -{spock-ref}[Spock] is used for testing the calling of the Mojo. -This will be downloaded by Maven. -Tests are run simply by: - - $ mvn clean test - -Or any of the other goals which run tests. -If I can figure out a good way to setup a Ruby testing environment I'll do that as well, but none exists at this time. - -== Resources - -To file an issue regarding this plugin, visit the {issues-ref}[plugin's repository]. - -Also, don't forget to join the {discuss-ref}[Asciidoctor discussion list], where you can ask questions and leave comments. diff --git a/docs/index.adoc b/docs/index.adoc index 744348309..a3dc016cc 100644 --- a/docs/index.adoc +++ b/docs/index.adoc @@ -12,6 +12,13 @@ You'll also find tips on how to be most productive when writing with the AsciiDo // include a list of irc handles for the main project devs TIP: Can't find the information you need? Reach out to project members and users via the http://discuss.asciidoctor.org/[discussion list] or the http://webchat.freenode.net/?channels=#asciidoctor[#asciidoctor] channel on Freenode IRC. +|=== +| link:../news/[*What’s New*] | link:getting-started/[*Getting Started*] +| link:asciidoc-syntax-quick-reference/[*Syntax Quick Reference*] | link:user-manual/[*User Manual*] +| link:asciidoc-writers-guide/[*Writer's Guide*] | link:developer-guide/[*Developer Guide*] +| link:asciidoc-recommended-practices/[*Recommended Practices*] | link:faq/[*FAQ*] +|=== + == The Basics Discover Asciidoctor and how it can help you. @@ -26,121 +33,10 @@ Discover Asciidoctor and how it can help you. * link:http://github.com/asciidoctor/asciidoctor/blob/master/LICENSE.adoc[What is the Asciidoctor license?] -// * How do AsciiDoc and Markdown differ? (Coming Soon) - -== Get Started with Asciidoctor - -Now, let's setup and use the Asciidoctor toolchain! - -* link:install-toolchain/[How do I install the Asciidoctor toolchain?] -+ -[sidebar] -.Using Mac OS X? -Follow the guide link:install-asciidoctor-macosx/[Installing Asciidoctor on Mac OS X] to get an in-depth tutorial. - -* link:render-documents[How do I render a document?] - -* link:produce-custom-themes-using-asciidoctor-stylesheet-factory[How do I use the Asciidoctor stylesheet factory to produce custom {rainbow-themes}?] - -* link:install-and-use-deckjs-backend[How do I create a deck.js presentation with Asciidoctor?] -* link:install-and-use-revealjs-backend[How do I create a reveal.js presentation with Asciidoctor?] - -//// -How do I render my document into DocBook? -How do I use a custom template? -//// - -== Write with Asciidoctor - -link:asciidoc-syntax-quick-reference/[AsciiDoc Syntax Quick Reference]:: - An overview of the AsciiDoc syntax you'll likely need to structure and format a document. - -link:asciidoc-writers-guide/[AsciiDoc Writer's Guide]:: - A comprehensive tutorial with examples that show you how to use the AsciiDoc syntax. - -link:user-manual/[Asciidoctor User Manual]:: - The A to Z guide to Asciidoctor. - -link:asciidoctor-diagram[Asciidoctor Diagram]:: - Learn how to create diagrams and ASCII art in your AsciiDoc documents using PlantUML, Graphviz, ditaa, and Shaape. - -link:asciidoc-recommended-practices/[AsciiDoc Style Guide and Recommended Practices] (DRAFT):: - Style tips and recommended practices for writing an easy to read and render document. - -//// -The AsciiDoc website also provides syntax documentation as well as http://asciidoc.org/userguide.html#_gotchas[Gotchas] and http://asciidoc.org/faq.html[FAQs] -//// - -== AsciiDoc Templates - -link:asciidoc-article/[AsciiDoc Article Template]:: - A template containing the most common content structures and markup used in an AsciiDoc article document. - -== Tools and Apps for Writing and Editing - -* link:editing-asciidoc-with-live-preview/[Editing AsciiDoc with Live Preview] - -//// -Blogging with AsciiDoc and Awestruct -Gist -Editor support -//// - -== Converters - -link:convert-asciidoc-to-pdf/[Convert AsciiDoc to PDF with Asciidoctor]:: - Asciidoctor PDF is a native PDF renderer for AsciiDoc. We're talking AsciiDoc direct to PDF! Learn how to install Asciidoctor PDF and use it to convert your AsciiDoc documents to PDF. - -link:convert-asciidoc-to-epub/[Convert AsciiDoc to EPUB3 with Asciidoctor]:: - Asciidoctor EPUB3 is a native EPUB3 renderer for AsciiDoc. Learn how to install Asciidoctor EPUB3 and use it to convert your AsciiDoc documents directly to EPUB3 and Amazon's KF8/Mobi format for Kindle. - -http://www.noteshare.io/section/asciidoctor-latex-manual-intro[Convert AsciiDoc to LaTeX with Asciidoctor]:: - An extension to Asciidoctor that (a) adds LaTeX-like features to Asciidoctor's HTML backend, (b) converts AsciiDoc documents to LaTeX and (c) converts LaTeX to AsciiDoc documents. - -== Integrations and Plugins - -* link:install-and-use-asciidoctor-java-integration/[How do I install and use the Asciidoctor Java integration?] - -* link:install-and-use-asciidoctor-gradle-plugin/[How do I install and use the Asciidoctor Gradle plugin?] - -* link:install-and-use-asciidoctor-maven-plugin/[How do I install and use the Asciidoctor Maven plugin?] - -* link:hack-asciidoctor-maven-plugin/[Hacking on the Asciidoctor Maven plugin] - -* link:install-and-use-asciidoclet/[How do I install and use Asciidoclet?] - -* link:install-and-use-asciidoctorjs/[How do I install and use Asciidoctor.js?] (Experimental) - -* link:extensions/[Extension list] - == Contribute to Asciidoctor //* link:/#submitting-an-issue[How do I report a bug?] * https://github.com/asciidoctor/asciidoctor/blob/master/CONTRIBUTING.adoc#submitting-an-issue[How do I report a bug?] //* ``I have code I'd like to contribute!'' Then checkout this guide => link:/#submitting-a-pull-request[How do I submit it to the project?] -* ``I have code I'd like to contribute!'' Then checkout this guide => https://github.com/asciidoctor/asciidoctor/blob/master/CONTRIBUTING.adoc#submitting-a-pull-request[How do I submit code to the project?] - -//// - -I have an idea about how to improve Asciidoctor? How do I tell you? - -How do I fix a problem on the Asciidoctor website? - -How do I edit the Asciidoctor documentation? - -//// - -== References and Developer Resources - -* link:faq/[FAQs and Troubleshooting] - -* link:user-manual/[Asciidoctor User Manual] - -* link:/rdoc/Asciidoctor.html[Asciidoctor Ruby API Documentation] - -* https://oss.sonatype.org/service/local/repositories/releases/archive/org/asciidoctor/asciidoctor-java-integration/0.1.2.1/asciidoctor-java-integration-0.1.2.1-javadoc.jar/!/org/asciidoctor/package-summary.html[Asciidoctor Java API Documentation] - -* link:/[Asciidoctor README] - -* link:/man/asciidoctor/[+asciidoctor+ man page] +* ``I have code I'd like to contribute!'' Then checkout this guide -> https://github.com/asciidoctor/asciidoctor/blob/master/CONTRIBUTING.adoc#submitting-a-pull-request[How do I submit code to the project?] \ No newline at end of file diff --git a/images/docker-logo.svg b/images/docker-logo.svg new file mode 100644 index 000000000..d239c4c2f --- /dev/null +++ b/images/docker-logo.svg @@ -0,0 +1,155 @@ + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/linux-logo.svg b/images/linux-logo.svg new file mode 100644 index 000000000..e48b73537 --- /dev/null +++ b/images/linux-logo.svg @@ -0,0 +1,902 @@ + + + Tux + For more information see: http://commons.wikimedia.org/wiki/Image:Tux.svg + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/images/macosx-logo.svg b/images/macosx-logo.svg new file mode 100644 index 000000000..e28f62bfd --- /dev/null +++ b/images/macosx-logo.svg @@ -0,0 +1,11 @@ + + + + + + + + + + + diff --git a/images/windows-logo.svg b/images/windows-logo.svg new file mode 100644 index 000000000..999c7059f --- /dev/null +++ b/images/windows-logo.svg @@ -0,0 +1,75 @@ + + + +image/svg+xml \ No newline at end of file