Как использовать уценку для сайта проекта maven?

Как начать с проектной документации с использованием языка разметки maven и markdown? По умолчанию сайт Maven является APT, что неудобно, чтобы научиться просто делать вещи maven. (Обычно никто в команде не начнет писать документацию на сайте maven, когда им также необходимо изучить еще один язык разметки на пути.)

Кто-нибудь пытался использовать markdown (тот же язык разметки, что и на github) для документации сайта проекта Maven? Я вижу из Maven Doxia ссылки, что это возможно. Любые проблемы?

Я новичок в создании сайта maven. Я думаю, что уценка лучше начать с других языков разметки, с которыми команда не работала.

UPDATE. Преемник. См. Ответ ниже.

Ответы

Ответ 1

Цитата из http://maven.apache.org/doxia/references/index.html

Добавьте это к pom.xml

          <plugin>    
              <groupId>org.apache.maven.plugins</groupId>
              <artifactId>maven-site-plugin</artifactId>
              <version>3.2</version>
              <dependencies>
                <dependency>
                  <groupId>org.apache.maven.doxia</groupId>
                  <artifactId>doxia-module-markdown</artifactId>
                  <version>1.3</version>
                </dependency>
              </dependencies>
            </plugin>

Затем добавьте страницы под src/site/markdown/ с расширением .md. Для каждой страницы добавьте пункт меню, например, в sniplet:

 <body>
    <!-- http://maven.apache.org/doxia/doxia-sitetools/doxia-decoration-model/decoration.html 
    <item collapse=.. ref=.. name=.. href="README" img=.. position=.. alt=.. border=.. width=.. height=.. target=.. title=.. >
    -->
    <menu name="User guide">
      <item href="README.html" name="README" />
    </menu>

    <menu ref="reports" inherit="bottom" />
  </body>

Чем использовать mvn site для создания сайта. Посмотрите target/site, чтобы просмотреть результаты.

mvn site:stage -DstagingDirectory=C:\TEMP\fullsite, чтобы получить многомодульный сайт проекта в одной папке.

Подробнее о maven-site-plugin.

Я рекомендую использовать maven-fluido-skin. Это новейший стиль, основанный на Twitter Bootstrap  Добавьте это на сайт .xml

<project name="xxx">
  [...]
  <skin>
    <groupId>org.apache.maven.skins</groupId>
    <artifactId>maven-fluido-skin</artifactId>
    <version>1.3.0</version>
  </skin>
  [...]
</project>

См. также https://github.com/winterstein/Eclipse-Markdown-Editor-Plugin

Ответ 2

Другим стандартным способом является использование Плагина сайта Maven, как показано ниже.

При таком подходе вы можете воспользоваться фильтрацией двигателя шаблонов скоростей. Таким образом, он добавляет больше возможностей для вашей документации.