[jira] [Commented] (ISIS-1133) Convert website to asciidoctor, hosted in git and published via ASF's svnpubsub

["ASF subversion and git services (JIRA)" <ji...@apache.org>]

    [ https://issues.apache.org/jira/browse/ISIS-1133?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14567042#comment-14567042 ] 

ASF subversion and git services commented on ISIS-1133:
-------------------------------------------------------

Commit 3162bda8582df0a553fe2cdde2b3597162cbfb00 in isis's branch refs/heads/ISIS-1133 from [~danhaywood]
[ https://git-wip-us.apache.org/repos/asf?p=isis.git;h=3162bda ]

ISIS-1133: more fixing up of references.


> Convert website to asciidoctor, hosted in git and published via ASF's svnpubsub
> -------------------------------------------------------------------------------
>
>                 Key: ISIS-1133
>                 URL: https://issues.apache.org/jira/browse/ISIS-1133
>             Project: Isis
>          Issue Type: Improvement
>          Components: Website and Docs
>    Affects Versions: core-1.8.0
>            Reporter: Dan Haywood
>            Assignee: Dan Haywood
>             Fix For: 1.10.0
>
>
> 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/



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)