Examples

Real-world examples and best practices for using Maven Skin.

Project Structure

Recommended Directory Layout

my-project/
├── pom.xml
├── src/
│   ├── main/
│   │   └── java/
│   ├── test/
│   │   └── java/
│   └── site/
│       ├── site.xml
│       ├── asciidoc/
│       │   ├── index.adoc
│       │   ├── getting-started.adoc
│       │   ├── installation.adoc
│       │   ├── usage/
│       │   │   ├── basic.adoc
│       │   │   └── advanced.adoc
│       │   └── api/
│       │       └── reference.adoc
│       ├── resources/
│       │   └── images/
│       │       └── logo.png
│       └── markdown/
│           └── other-format.md
├── .github/
│   └── workflows/
│       └── pages.yml
└── target/
    └── site/  (generated)

File Organization Best Practices

Keep it organized: * Group related pages in subdirectories * Use descriptive file names * Maintain consistent naming conventions * One topic per file.

AsciiDoc Examples

Basic Document Structure

= Document Title
Author Name
:toc:
:toclevels: 3
:source-highlighter: coderay

== Introduction

This is the introduction section.

=== Subsection

More details here.

== Main Section

Content for main section.

=== Code Example

[source,java]
----
public class Hello {
  public static void main(String[] args) {
      System.out.println("Hello, World!");
  }
}
----

=== Lists

* Item 1
* Item 2
  ** Nested item
  ** Another nested

. First
. Second
. Third

== See Also

* link:other-page.html[Other Page]
* https://example.com[External Link]

Renders as:

Document Title

Author Name

Introduction

This is the introduction section.

Subsection

More details here.

Main Section

Content for main section.

Code Example
public class Hello {
  public static void main(String[] args) {
      System.out.println("Hello, World!");
  }
}
Lists
  • Item 1
  • Item 2
    • Nested item
    • Another nested
      1. First
      2. Second
      3. Third

Tables

== Feature Comparison

|===
| Feature | Maven Skin | Other Skin

| Dark Mode
| ✓
| ✗

| Responsive
| ✓
| ✓

| AsciiDoc
| ✓
| ✗

| Modern Design
| ✓
| ✗
|===

Renders as:

Feature Maven Skin Other Skin
Dark Mode ✓ ✗
Responsive ✓ ✓
AsciiDoc ✓ ✗
Modern Design ✓ ✗

Code Blocks with Syntax Highlighting

Java

[source,java]
----
public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }
}
----

Renders as

public class Calculator {
    public int add(int a, int b) {
        return a + b;
    }
}

XML

[source,xml]
----
<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-app</artifactId>
</project>
----

Renders as

<project>
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>my-app</artifactId>
</project>

JSON

[source,json]
----
{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A great project"
}
----

Renders as

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A great project"
}

Bash

[source,bash]
----
#!/bin/bash
echo "Hello, World!"
mvn clean install
----

Renders as:

#!/bin/bash
echo "Hello, World!"
mvn clean install

Cross-References and Links

==== Getting Started

See link:getting-started.html[Getting Started Guide].

Or link:installation.html#custom-domain[Custom Domain Setup].

External: https://example.com[Example Website]

Relative: xref:../other-page.adoc[Other Page]

Renders as:

Getting Started

See Getting Started Guide.

Or Custom Domain Setup.

External: Example Website

Relative: Other Page

Admonitions (Notes, Warnings, Tips)

NOTE: This is something to note.

WARNING: Be careful with this!

TIP: Here's a helpful tip.

IMPORTANT: This is really important.

CAUTION: Proceed with caution!

Renders as:

Real-World Examples

Office-Stamper Example

Office-Stamper uses Maven Skin for its documentation. Visit office-stamper.verron.pro to see it in action.

Key features demonstrated:

  • Multi-section documentation
  • API reference pages
  • Getting started guides
  • Real code examples
  • Professional appearance

Site structure:

office-stamper/
├── src/site/
│   ├── site.xml
│   └── asciidoc/
│       ├── index.adoc (Homepage)
│       ├── getting-started.adoc
│       ├── api-documentation.adoc
│       ├── examples/
│       │   ├── basic-usage.adoc
│       │   ├── advanced-features.adoc
│       │   └── troubleshooting.adoc
│       └── resources/
│           └── images/
│               └── workflow-diagram.png
└── .github/workflows/
    └── pages.yml (Auto-deployment)

Maven Skin Self-Documentation

This Maven Skin documentation at maven-skin.verron.pro is built using Maven Skin itself!

Demonstrates:

  • Clean, organized structure
  • Multiple guides and tutorials
  • Responsive tables and code blocks
  • Dark/light mode switching
  • Automatic deployment workflow