Examples & Best Practices

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

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]

Tables

== Feature Comparison

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

| Dark Mode
| ✓
| ✗

| Responsive
| ✓
| ✓

| AsciiDoc
| ✓
| ✗

| Modern Design
| ✓
| ✗
|===

Renders as:

Code Blocks with Syntax Highlighting

Java:

[source,java]

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>

JSON:

[source,json]

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

Bash:

[source,bash]

#!/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]

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!

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

Documentation Organization

Do: ✓ Group related topics together ✓ Use descriptive titles ✓ Keep sections focused and concise ✓ Link related pages ✓ Provide examples

Don’t: ✗ Mix unrelated topics in one page ✗ Use vague titles ✗ Create overly long pages ✗ Leave broken links ✗ Forget to update old documentation

Writing for Mobile

Maven Skin is responsive. When writing documentation:

• Use shorter paragraphs
• Use descriptive headers (helps screen readers)
• Avoid very wide code lines
• Use tables sparingly (stack on mobile)
• Test locally with mvn site and check mobile rendering

Dark Mode Considerations

Content looks good in both themes:

• Avoid hardcoding colors in images
• Use high contrast for text
• Use semantic HTML (provided by AsciiDoc)
• Test both light and dark modes
• Don’t rely on color alone to convey information

Example: Instead of "Click the red button", use "Click the Send button".

Performance Optimization

Optimize your site:

• Keep images reasonably sized (~50-100KB each)
• Use descriptive image names
• Organize CSS and JavaScript efficiently
• Minimize external dependencies
• Use <placeholder> for large code examples
• Link to large resources instead of embedding

Versioning

Multiple documentation versions:

If you maintain multiple versions:

<!-- In site.xml -->
<menu name="Documentation">
  <item name="Latest (1.0)" href="/latest"/>
  <item name="1.0" href="/docs/1.0"/>
  <item name="0.9" href="/docs/0.9"/>
</menu>

Or use GitHub branches:

git checkout -b docs-v1.0
# Modify documentation
git push origin docs-v1.0
# Set up separate GitHub Pages for this branch

Installation Instructions

== Installation

=== Prerequisites

* Java 11+
* Maven 3.6+

=== Steps

. Download from https://example.com[example.com]
. Extract the archive
. Run: `mvn clean install`
. Verify: `mvn --version`

=== Next Steps

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

API Documentation

== API Reference

=== Class: MyService

[source,java]

public class MyService { /** * Process the input data. * @param input the input to process * @return the processed result */ public String process(String input) { // …​ } }

.Parameters
|===
| Parameter | Type | Description

| input
| String
| The data to process
|===

.Returns
|===
| Type | Description

| String
| The processed result
|===

.Example
[source,java]

MyService service = new MyService(); String result = service.process("data");

Troubleshooting Guide

== Troubleshooting

=== Error: "Connection Refused"

.Problem
Your application fails to start with "Connection Refused" error.

.Cause
The port is already in use or the service is not running.

.Solution
. Check if the port is in use: `lsof -i :8080`
. Kill the process using the port
. Restart your application

See <<configuration>> for port settings.

[[configuration]]
=== Configuration

Configure the port in `application.yml`:

[source,yaml]

server: port: 8081

Keeping Documentation Current

Set a schedule:

• Review documentation quarterly
• Update examples with new versions
• Fix broken links regularly
• Archive old documentation
• Encourage community contributions

Content Update Workflow

# 1. Edit documentation
vim src/site/asciidoc/my-page.adoc

# 2. Test locally
mvn clean site
open target/site/index.html

# 3. Commit changes
git add src/site/
git commit -m "Update documentation: added new section"

# 4. Push to trigger deployment
git push origin main

# 5. Verify on GitHub Pages
# Visit: https://your-domain.com

AsciiDoc Tools

• Asciidoctor - Official documentation
• User Manual - Complete reference
• Writer’s Guide - Best practices

Maven Resources

• Maven Site Plugin
• Maven Guides

Related Projects

• Office-Stamper - Document template engine
• Verron.pro - Blog with compatible styling

Automatic TOC

Add to top of your document:

:toc:
:toclevels: 3

Code Block Callouts

[source,java]

public class Hello { System.out.println("Hello"); // <1> }

<1> This line prints the greeting

Attributes

:project-name: My Project
:version: 1.0.0

== {project-name} v{version}

Welcome to {project-name}!

Include External Files

include::../code-examples/HelloWorld.java[]

This helps keep documentation and code examples in sync.