Uploaded image for project: 'Isis'
  1. Isis
  2. ISIS-1133

Convert website to asciidoctor, hosted in git and published via ASF's svnpubsub



    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: core-1.8.0
    • Fix Version/s: 1.9.0
    • Component/s: Isis Docs & Website
    • Labels:


      Asciidoctor can be found here [1].

      Some reasons for doing this:

      • the source code for the website will be in git (rather than svn as currently), and so will be mirrored to github. Therefore users/contributors can fork our repo and submit pull requests on the docs/website.
      • the generated content can be previewed locally; ASF's svnpubsub infrastructure is used only for publishing/hosting the site
      • there are also some doubts about svnpubsub's long-term future, so we should minimize our dependence on it if possible
      • the toolchain seems to exist already and is in use by at least one other ASF project - Deltaspike [2] - who have got the toolchain to work. (Wicket are also experimenting, [3])
      • the generated pages are themeable either using Foundation (the default) or using Bootstrap .
      • github natively understands asciidoc (.adoc) files, and are enthusiastic supporters (see this article of Scott Chacon, [4])
      • there are editors for Asciidoctor, eg [5]
      • longer term, it's possible that the docs could be converted into a book, eg using O'Reilly's Atlas platform [6]

      Good starting points:

      • the DeltaSpike pom.xml's. They seem to have two separate regions; the top-level site [7a,7b], and a "documentation" subfolder [8a,8b]
      • these use the asciidoctor-maven-plugin [9] to convert the .adoc files to .html
      • these use the maven-scm-publish-plugin [10] to update the SVN (do all necessary add/deletes to properly synchronize)
      • there are also some useful templates (integrated with mvn site) at [11]
      • theming with Bootstrap might be done using any of [12] or [13a, 13b] (latter is asciidoc not asciidoctor so might require some fiddling around with).

      [1] http://asciidoctor.org/
      [2] http://deltaspike.apache.org/
      [3] https://github.com/dashorst/wicketguide
      [4] https://medium.com/@chacon/living-the-future-of-technical-writing-2f368bd0a272
      [5] https://github.com/asciidoctor/atom-asciidoc-preview
      [6] https://atlas.oreilly.com/
      [7a] https://github.com/apache/deltaspike/blob/master/site
      [7b] https://github.com/apache/deltaspike/blob/master/site/pom.xml
      [8a] https://github.com/apache/deltaspike/tree/master/documentation
      [8b] https://github.com/apache/deltaspike/tree/master/documentation/pom.xml
      [9] http://asciidoctor.org/docs/asciidoctor-maven-plugin/
      [10] https://maven.apache.org/plugins/maven-scm-publish-plugin/
      [11] https://github.com/asciidoctor/asciidoctor-maven-examples
      [12] https://github.com/nerk/asciidoctor-bs-themes
      [13a] https://github.com/llaville/asciidoc-bootstrap-backend
      [13b] http://laurent-laville.org/asciidoc/bootstrap/




            • Assignee:
              danhaywood Daniel Keir Haywood
            • Votes:
              0 Vote for this issue
              2 Start watching this issue


              • Created: