Table of Contents

Sentry Maven Skin 6.4.01

Getting Started

Prerequisites

The following is absolutely required to use the Sentry Maven Skin:

Setup of your site project

Directory layout

Below is the typical directory layout of a documentation site project with Maven:

./  pom.xml
│
└───src/
    └───site/
        │   site.xml
        │
        ├─── markdown/
        │       index.md
        │
        └─── resources/
            ├─── css/
            │       site.css
            │
            └─── images/

pom.xml

The Sentry Maven Skin leverages Sentry's Skin Tools Java library[3], that needs to be declared as a dependency when invoking the maven-site-plugin. Update you Maven pom.xml as below:

<build>
  <plugins>
    ...
    <plugin>
      <artifactId>maven-site-plugin</artifactId>
      <version>3.12.1</version>
      ...
      <dependencies>
        <dependency>
          <groupId>org.sentrysoftware.maven</groupId>
          <artifactId>maven-skin-tools</artifactId>
          <version>1.3.00</version> <!-- Check for the latest version -->
        </dependency>
      </dependencies>
    </plugin>
    ...
  </plugins>
</build>

site.xml

Then, specify the Sentry Maven Skin artifact in your src/site/site.xml file:

<project name="${project.name}">

  <!-- Use Sentry Maven Skin -->
  <skin>
    <groupId>org.sentrysoftware.maven</groupId>
    <artifactId>sentry-maven-skin</artifactId>
    <version>6.4.01</version>
  </skin>

  <!-- Sentry Maven Skin specific settings -->
  <custom>
    <bodyClass>sentry-purple</bodyClass> <!-- banner color -->
    <keywords>keyword1,keyword2</keywords> <!-- keywords in all pages -->
      <additionalLinks> <!-- additional links in the footer -->
        <link>
          <name>Code of Ethics</name>
          <href>ethics.html</href>
        </link>
    </additionalLinks>
    <social>
      <linkedin>company/microsoft</linkedin>
    </social>
  </custom>

  <!-- Top link -->
  <bannerLeft>
    <name>${project.organization.name}</name>
    <href>${project.organization.url}</href>
    <!-- Use <src>images/logo-100x40.png</src> to display a logo, instead of <name> -->
  </bannerLeft>

  <body>

    <!-- Links in the top navigation bar -->
    <links>
      <item name="Link 1" href="https://some.url"/>
      <item name="Another Resource" href="https://other.site"/>
    </links>

    <!-- Documentation content on the left -->
    <menu name="First Menu Group">
      <item name="Overview" href="index.html"/>
      <item name="Other Page" href="other-page.html"/>
    </menu>

    <!-- 3 levels: menus (groups), items (pages), and sub-items (pages) -->
    <menu name="Second Menu Group">
      <item name="Write a Good Documentation" href="writing.html"/>
      <item name="Using Subdirectories" href="subdir/using.html"/>
      <item name="Big Chapter" href="big-chapter/index.html">
        <item name="Sub Topic 1" href="big-chapter/subtopic1.html" />
        <item name="Sub Topic 2" href="big-chapter/subtopic2.html" />
      </item>
    </menu>

  </body>

</project>

Content

Write the content of your documentation in the ./src/site/markdown/ directory if you choose to use Markdown. Other markup languages are supported, like APT, Confluence or XHTML. The Maven documentation explains how to create content for a documentation site[1].

Styling

You can customize the look and feel[4] of your documentation by writing a CSS stylesheet in ./src/site/resources/css/site.css that overrides the skin's CSS variables as in the example below:

body {
  --banner-bgcolor: #266fd0;
  --alternate-bgcolor: var(--banner-bgcolor);
  --alternate-fgcolor: var(--banner-fgcolor);
  --link-color: #d50c37;
}

/* Lighter red for dark mode ('dark' class on the <body> element) */
body.dark {
  --link-color: #ff6989;
}

Generating the documentation site

You're then good to go to build your documentation site:

mvn clean site

The site is built in target/site/*.

Live rendering

Additionally, you can build the site live and make it available on a local Web server with the below command:

mvn site:run

This command spawns a Web server with the content of your documentation site. Each page is rendered live when you request it in your browser, so changes in your Markdown are taken into account immediately. This is particularly useful when you write your documentation and needs to see how it looks very quickly.

Note

Only the changes in your documentation sources (e.g. the Markdown *.md files) are taken into account. Changes in site.xml or pom.xml require to restart mvn site:run.

doxia maven skin doxia
Links:
  • [1] https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html
  • [2] https://maven.apache.org/plugins/maven-site-plugin
  • [3] https://sentrysoftware.github.io/maven-skin-tools/
  • [4] styles.html
No results.