• 设为首页
  • 点击收藏
  • 手机版
    手机扫一扫访问
    迪恩网络手机版
  • 关注官方公众号
    微信扫一扫关注
    迪恩网络公众号

asciidoctor/asciidoctor-maven-examples: A collection of example projects that de ...

原作者: [db:作者] 来自: 网络 收藏 邀请

开源软件名称(OpenSource Name):

asciidoctor/asciidoctor-maven-examples

开源软件地址(OpenSource Url):

https://github.com/asciidoctor/asciidoctor-maven-examples

开源编程语言(OpenSource Language):

CSS 43.2%

开源软件介绍(OpenSource Introduction):

Asciidoctor Maven Plugin: Examples

This repository contains a collection of sample projects that demonstrate numerous ways to use the Asciidoctor Maven plugin in a Maven project.

Getting the examples

Clone the example repository using git:

$ git clone https://github.com/asciidoctor/asciidoctor-maven-examples

Refer to the README file in each individual project to learn how to run it.

Example catalog

asciidoc-to-html-example (aka “The Quickstart”)

Demonstrates how to convert AsciiDoc to HTML5 using the Asciidoctor Maven plugin.

asciidoc-to-html-multipage-example

Demonstrates how to convert AsciiDoc to multiple HTML pages with the Asciidoctor Maven plugin and Asciidoctor Multipage Extension.

docbook-pipeline-docbkx-example

Demonstrates how to convert AsciiDoc to DocBook and feed it to the DocBook pipeline to generate a PDF using the Asciidoctor and Docbkx Maven plugins.

asciidoctor-diagram-example

Demonstrates how to integrate Asciidoctor Diagram with the Asciidoctor Maven plugin.

asciidoctor-pdf-example

Demonstrates how to convert AsciiDoc to PDF using Asciidoctor PDF with the Asciidoctor Maven plugin.

asciidoctor-epub-example

Demonstrates how to convert AsciiDoc to epub using Asciidoctor EPUB with the Asciidoctor Maven plugin. (contains also an example for .mobi (Kindle) output)

asciidoc-maven-site-example

Demonstrates how to process AsciiDoc in a Maven site using the Asciidoctor Maven plugin.

asciidoc-multiple-inputs-example

An example project that demonstrates how to convert multiple input AsciiDoc documents to HTML5 and PDF using the Asciidoctor Maven plugin.

java-extension-example

An example project that demonstrates how to create an extension for Asciidoctorj (written in Java) and how to use it in an other documentation Maven module.

asciidoc-to-revealjs-example

Demonstrates how to convert AsciiDoc to reveal.js using Asciidoctor revealjs with the Asciidoctor Maven plugin.

Root pom.xml

The root pom.xml (aggregate build) is provided to allow you to run all the example projects at once using a single invocation of Maven. It also drives the continuous integration (CI) build. The root pom.xml does not contain any shared build configuration so that each of the projects can be used independently. This makes the examples suitable as independent references and as a starting point for your own project.

Usage

Invoke the compile goal (configured as the default goal) on this folder (asciidoctor-maven-example):

$ mvn

On JRuby dependency

Asciidoctor Maven plugin relies on asciidoctor project to do the actual rendering. This is a Ruby implementation integrated thanks to the JRuby project, which is a required dependency to run the plugin. The maven plugin provides a default version of the jruby-complete artifact to ease its configuration. However, it can be overwritten just adding a custom version in the plugin’s dependency section as seen in the following example:

  <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>${asciidoctor.maven.plugin.version}</version>
      <dependencies>
          <dependency>
              <groupId>org.jruby</groupId>
              <artifactId>jruby-complete</artifactId>
              <version>${jruby.version}</version>
          </dependency>
      <dependencies>
  </plugin>

Updating Asciidoctor Maven plugin version

In case it is required to test a specific version of the plugin (e.g. local SNAPSHOT version), a tool has been included to update the version in all examples. Properties can be updated in two ways.

  • First, define the new versions using the versions system property, this will update in examples as well as in the parent. The following example shows how to update two properties.

  $ mvn validate -Pupdate-properties -Dversions=asciidoctor.maven.plugin.version=1.6.0-SNAPSHOT,asciidoctorj.pdf.version=1.5.0-alpha.12
  • Secondly, copying the properties values from the parent pom to the example projects. For example, to change the plugin’s version follow the next steps:

    1. Set the desired version in the <asciidoctor.maven.plugin.version> property in the pom.xml file located at the root (asciidoctor-maven-examples folder). For instance:

  <asciidoctor.maven.plugin.version>2.2.2</asciidoctor.maven.plugin.version>
  1. Execute the validate maven goal with the update-properties profile:

  $ mvn validate -Pupdate-properties

Contributing

We want you! Yes, you.

Anyone can contribute to an Asciidoctor project. If you have a specialty, or just some creativity to share, we need your participation. We have big aspirations for the project and we need an assortment of skill sets in order to reach them. Make no mistake, contributing is not just for developers.

Of course, we’ll always need help with the code as it’s the basis of the project. But code isn’t going to make the project successful alone. We also need documentation, automation, design, marketing, communication, advocacy and more for it to make an impact.

Here are just a few of the ways you can contribute to the project:

  • Reporting bugs (The easiest way to get started!)

  • Sharing ideas on https://asciidoctor.zulipchat.com/ or https://discuss.asciidoctor.org

  • Suggesting new feature or improvements in the issue tracker

  • Speaking about the technology

  • Advocating for the technology

  • Assisting with design and/or UX (stylesheets, themes, logos, etc)

  • Conducting user studies and collecting feedback

  • Automating system administration tasks (releases, changelog, announcements, hosting, etc)

  • Writing, editing or maintaining the documentation

  • Organizing the content (information architecture & content strategy)

  • Using or extending the software in a creative way

  • Testing a prerelease, a pull request or master

  • Reviewing or providing feedback on pull requests

  • Writing code (No patch is too small!)

    • Fixing typos

    • Adding or revising comments or API docs

    • Fixing issues

    • Writing tests

    • Refactoring the code

  • Something we haven’t suggested…​seriously!

The best way to get involved is just to show up and express your interest. We have a very friendly and encouraging culture. Harassment or offensive behavior is simply not tolerated. We are positive, even when being critical. We also strive to lift others up and help them be successful. We want your choice to participate in an Asciidoctor project be the start of an exciting and rewarding journey. So thanks for showing up!

Code conventions

Even when this project does not contain much code, we encourage the following good practices to improve accessibility and ease the use of the examples:

  • Document relevant details of an example in the appropriate README file

    • what makes this example useful

    • relevant components used (backends, extensions, …​)

    • how to execute the example and see the results

    • possible use scenarios

  • Comment relevant Java methods and classes, especially when writing extensions

  • Follow simples code conventions to improve readability on the web

    • Use 4 white spaces instead of tabs

    • Avoid long lines in the Java code (they’re good in AsciiDoc files though)

To help fixing some style conventions a small script has been included. Currently, it only checks for tabs, which should be replaced by white spaces. To see what files contain some inconsistency, run this command from the parent project.

  $ mvn validate -Pcheck-styles

If you want it to fix the issues for you, just add -Dfix to the command.

  $ mvn validate -Pcheck-styles -Dfix

Copyright © 2014 The Asciidoctor Project. Free use of this software is granted under the terms of the MIT License.

See the LICENSE.adoc file for details.




鲜花

握手

雷人

路过

鸡蛋
该文章已有0人参与评论

请发表评论

全部评论

专题导读
上一篇:
r-devops/mavenrepo发布时间:2022-08-16
下一篇:
anujdevopslearn/MavenBuild发布时间:2022-08-16
热门推荐
阅读排行榜

扫描微信二维码

查看手机版网站

随时了解更新最新资讯

139-2527-9053

在线客服(服务时间 9:00~18:00)

在线QQ客服
地址:深圳市南山区西丽大学城创智工业园
电邮:jeky_zhao#qq.com
移动电话:139-2527-9053

Powered by 互联科技 X3.4© 2001-2213 极客世界.|Sitemap