Skip to content

microprofile/microprofile-tutorial

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

102 Commits
.devcontainer
.devcontainer
 
 
.github/workflows
.github/workflows
 
 
build
build
 
 
code
code
 
 
images
images
 
 
minimal-component
minimal-component
 
 
modules/ROOT
modules/ROOT
 
 
supplemental-ui
supplemental-ui
 
 
.gitignore
.gitignore
 
 
CONTRIBUTORS.adoc
CONTRIBUTORS.adoc
 
 
DEVELOPERS.adoc
DEVELOPERS.adoc
 
 
LICENSE
LICENSE
 
 
README.adoc
README.adoc
 
 
antora-assembler.yml
antora-assembler.yml
 
 
antora.yml
antora.yml
 
 
dev-server.sh
dev-server.sh
 
 
fix-edit-links.sh
fix-edit-links.sh
 
 
index.adoc
index.adoc
 
 
package-lock.json
package-lock.json
 
 
package.json
package.json
 
 
redirect.html
redirect.html
 
 
test-pdf-download.sh
test-pdf-download.sh
 
 
update-repo-url.sh
update-repo-url.sh
 
 

Repository files navigation

MicroProfile Tutorial

The MicroProfile Tutorial is a comprehensive guide for learning about MicroProfile. This repository contains both the documentation (built with Antora) and the source code examples for the tutorial.

Table of Contents

What’s New in MicroProfile 7.1 Tutorial

The MicroProfile Tutorial has been updated to reflect the latest features and changes in MicroProfile 7.1.

Version and Branch Strategy

This repository uses a branch-per-version strategy to maintain documentation and code examples for different MicroProfile releases. Each MicroProfile version has its own dedicated branch, ensuring long-term maintainability and clear separation between versions.

Why Version-Specific Branches?

We maintain separate branches for each MicroProfile version instead of using a single main branch because:

1. Long-term Version Maintenance

  • Each MicroProfile version follows its own lifecycle (6.1, 7.0, 7.1, 7.2, 8.0, etc.)

  • Versions may need independent bug fixes, clarifications, or dependency updates

  • With version-specific branches, we can update any version without affecting others

2. Clear Reference Points

  • Developers often work on projects locked to specific MicroProfile versions for compatibility

  • Stable branch URLs (e.g., tree/v6.1, tree/v7.1) provide permanent, bookmarkable references

  • Users can easily find code examples matching their project’s MicroProfile version

  • Documentation URLs remain stable even as new versions are released

3. Parallel Development

  • We can work on future versions (7.2, 8.0) while earlier versions are still stabilizing

  • Separate branches allow preview/beta content without disrupting stable documentation

  • Teams can contribute to different versions simultaneously

4. Easier Comparison & Migration

  • Branches make it trivial to compare differences between versions

  • Helps users understand breaking changes and migration paths (e.g., git diff v6.1 v7.1)

  • Clear separation of version-specific code examples and API usage

5. Antora Multi-version Support

  • Antora is specifically designed to build documentation from multiple branches

  • Our build system automatically generates version-specific content (e.g., build/site/microprofile-tutorial/6.1/ and 7.1/)

  • Users get a version selector in the UI to switch between versions seamlessly

6. Avoiding "Moving Target" Problem

  • If we used main for 7.1 today, what happens when 7.2 ships?

  • Version branches eliminate confusion about which version you’re looking at

  • Each branch represents a stable target for learners and enterprise users

Branch Organization

Branch MicroProfile Version Status

v6.1

6.1

Stable - maintenance mode

v7.1

7.1

Active development

main

Landing/Navigation

README and Antora configuration

Future: v7.2, v8.0

7.2, 8.0

Not yet created

Which Branch Should You Use?

Choose the branch that matches your MicroProfile version:

  • For MicroProfile 6.1 projects: Use the v6.1 branch

  • For MicroProfile 7.1 projects: Use the v7.1 branch

  • For the latest stable version: Check the badges or releases page

Branches vs. Releases

Branches (v6.1, v7.1) are living documentation:

  • Can be continuously updated with fixes, improvements, and clarifications

  • Antora builds the documentation site from these branches

  • Used for active development and ongoing maintenance

GitHub Releases (v6.1.0, v7.1.0) are immutable snapshots:

  • Mark official milestones (e.g., "Tutorial completed for MP 7.1")

  • Provide downloadable archives of specific versions

  • Useful for citations, training certifications, or enterprise policies

  • Created from branch tags at significant points

You can use both: follow a branch for the latest updates, or download a specific release for a fixed reference.

Workflow for New Versions

When creating documentation for a new MicroProfile version:

  1. Create a new version branch from the most recent version:

    git checkout v7.1
git checkout -b v7.2

  2. Update version numbers throughout the branch:

    • antora.yml - Component version and display version

    • All pom.xml files in code/ directory - MicroProfile and dependency versions

    • Documentation content referencing version numbers

  3. Update code examples to use new MicroProfile features and APIs

  4. Test the build locally before pushing:

    antora antora-assembler.yml

  5. Push the branch to the repository:

    git push -u origin v7.2

  6. Update antora-assembler.yml in main branch to include the new version in builds

  7. Create a GitHub Release when the version reaches a stable milestone

Building Multiple Versions

The antora-assembler.yml file is configured to build documentation for multiple versions simultaneously. This:

  • Creates a version selector in the documentation UI

  • Allows users to switch between different MicroProfile versions easily

  • Builds all versions from their respective branches in a single site

  • Maintains separate navigation and content for each version

Prerequisites

Install Antora

You need to install Antora using npm. If you don’t have Node.js installed, you can install Node.js by following this instructions.

npm install -g @antora/cli @antora/site-generator-default

Recommended VS Code Extensions

For the best experience editing AsciiDoc files in Visual Studio Code, we recommend installing the following extensions:

  • AsciiDoc extension by Asciidoctor (asciidoctor.asciidoctor-vscode) - Provides rich language support for AsciiDoc

  • Auto Open Preview Panel (matt-rudge.auto-open-preview-panel) - Opens preview automatically when opening AsciiDoc files

Building the Documentation Site

You can build the site by running the following commands in the root directory of the project:

./update-repo-url.sh
antora antora-assembler.yml
./fix-edit-links.sh

  • The first command ensures that the repository URLs are up-to-date.

  • The second command will generate the site in the build/site directory.

  • The third command fixes the "Edit this Page" links to properly point to GitHub instead of local file paths.

Alternatively, you can use the following one-liner:

./update-repo-url.sh && antora antora-assembler.yml && ./fix-edit-links.sh

Running the Site Locally

You can run the site locally using Python’s built-in HTTP server. First, navigate to the build/site directory:

cd build/site

Then, run the following command:

python3 -m http.server 8080

This will start a local server on port 8080. You can then open your web browser and navigate to http://<hostname>:8080 to view the site.

Tip

If port 8080 is already in use, you can free it by finding and stopping the process using it. For example, on Linux or macOS:

+

lsof -i :8080
kill <PID>

Replace <PID> with the process ID shown in the output.

Development Workflow

To streamline the development process, a development server script is included that can automatically rebuild the documentation when files change.

Using the Development Server

The dev-server.sh script provides three commands:

  1. Build only:

    ./dev-server.sh build

    This builds the documentation site once.

  2. Build and serve:

    ./dev-server.sh serve

    This builds the documentation site and starts a local HTTP server on port 8080.

  3. Build, serve, and watch for changes:

    ./dev-server.sh watch

    This builds the documentation site, starts a local HTTP server, and automatically rebuilds the site when files change.

Requirements

The development server requires:

  • Python 3 (for the HTTP server)

  • inotify-tools (for file watching, will be automatically installed if missing)

Typical Development Workflow

  1. Start the development server in watch mode: ./dev-server.sh watch

  2. Open your browser at http://localhost:8080

  3. Edit AsciiDoc files in the modules/ROOT/pages/ directory

  4. Save your changes and see them automatically reflected in the browser

Understanding Antora Configuration

Antora uses several configuration files to manage the documentation site. The main files are:

  • antora-assembler.yml: The primary configuration file that defines the site structure, UI bundle, and supplemental files.

  • antora.yml: Component configuration for the MicroProfile Tutorial, including metadata and edit URL configuration.

  • supplemental-ui/: Directory containing customizations like favicons and custom partials.

Site Structure Configuration

The main configuration file for the site is antora-assembler.yml, which defines:

  • Site metadata: Title, URL, and starting page

  • Content sources: Where to find documentation content

  • UI bundle: The theme and UI components to use

  • Output: Where to generate the site

  • Asciidoc attributes: Global attributes for all pages

Here’s a breakdown of the key sections:

Site Information

site:
  title: MicroProfile Tutorial
  url: https://microprofile.io
  start_page: microprofile-tutorial::index.adoc
  keys:
    show_edit_page_link: true

Content Sources

content:
  sources:
    - url: .
      start_path: .
      branches: HEAD

UI Configuration

ui:
  bundle:
    url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip
    snapshot: true
  supplemental_files: ./supplemental-ui

Component Configuration

The antora.yml file defines the documentation component:

name: microprofile-tutorial
title: MicroProfile Tutorial
version: 6.1
edit_url: https://github.com/microprofile/microprofile-tutorial/tree/main/modules/ROOT/pages/{path}
asciidoc:
  attributes:
    source-language: asciidoc@
    table-caption: false
    xrefstyle: full
nav:
  - modules/ROOT/pages/nav.adoc
start_page: index.adoc

Key properties:

  • name: The component name used in xrefs and URLs

  • title: The human-readable title

  • version: The component version (appears in URLs and version selector)

  • edit_url: The URL template for "Edit this Page" links

  • nav: The navigation file(s) for the component

  • start_page: The default page when accessing the component root

Navigation Configuration

The navigation is defined in modules/ROOT/pages/nav.adoc and uses AsciiDoc with special Antora directives:

* xref:index.adoc[Home]
* xref:chapter01/chapter01.adoc[Chapter 1: Introduction]
* Chapter 2: Getting Started
** xref:chapter02/chapter02-01.adoc[Section 2.1: Environment Setup]

The navigation structure directly affects the sidebar menu in the generated site.

Navigation and Site Structure

The navigation system in Antora is a critical component that determines how users find and access content. Understanding how navigation works can help you create a better user experience.

Navigation Components

The MicroProfile Tutorial site navigation consists of:

  1. Main Navigation: Defined in modules/ROOT/pages/nav.adoc, controls the sidebar navigation.

  2. Breadcrumbs: Shows the current page’s location in the content hierarchy.

  3. Previous/Next Links: Helps users navigate sequentially through content.

  4. Table of Contents: Generated from page headings, provides in-page navigation.

Customizing Navigation

The navigation can be customized in several ways:

Modifying the nav.adoc File

The main navigation structure is defined in modules/ROOT/pages/nav.adoc:

* xref:index.adoc[Home]
* xref:chapter01/chapter01.adoc[Chapter 1: Introduction]
* Chapter 2: Getting Started
** xref:chapter02/chapter02-01.adoc[Section 2.1: Environment Setup]
** xref:chapter02/chapter02-02.adoc[Section 2.2: First Steps]

Navigation entries can be:

  • Direct links to pages (with xref:)

  • Unlinked category headers (without xref:)

  • Nested to create hierarchical structures (using multiple * characters)

Navigation UI Customization

To customize the navigation appearance:

  1. Style Overrides: Add CSS for navigation elements in your supplemental UI files.

  2. Template Customization: Override the navigation templates in the UI bundle.

  3. JavaScript Enhancements: Add interactive features like search, filtering, or collapsible sections.

Example CSS customization for navigation:

/* Customizing the sidebar navigation */
.nav-menu {
  background-color: #f5f5f5;
}

.nav-item.is-current-page > .nav-link {
  color: #0d5aa7;
  font-weight: bold;
}

Navigation Best Practices

  1. Logical Organization: Group related content together in the navigation.

  2. Consistent Naming: Use consistent naming conventions for pages and sections.

  3. Limited Nesting: Avoid deep nesting (more than 3 levels) to prevent navigation complexity.

  4. Descriptive Labels: Use clear, descriptive labels for navigation items.

  5. Progressive Disclosure: Organize content from basic to advanced topics.

Advanced Navigation Features

The UI bundle can be customized to include advanced navigation features:

  1. Search Integration: Add search functionality to help users find content quickly.

  2. Version Selector: Allow users to switch between different versions of the documentation.

  3. Component Selector: If you have multiple components, provide a way to navigate between them.

  4. Tag-Based Navigation: Group content by tags or categories for alternative navigation paths.

About the fix-edit-links.sh Script

The fix-edit-links.sh script is a necessary post-processing step in the build process. Despite having edit_url properly configured in antora.yml, when building from a local repository (url: . in antora-assembler.yml), Antora generates edit links that point to local file paths instead of GitHub URLs.

The script performs a simple text replacement in the generated HTML files, replacing local file paths with proper GitHub repository URLs. This ensures that the "Edit this Page" links work correctly for users viewing the documentation.

If you update the repository URL or branch name, make sure to update the replacement URL in the fix-edit-links.sh script accordingly. The current implementation assumes the GitHub repository URL is https://github.com/microprofile/microprofile-tutorial and the branch is main.

Automating Repository URL Configuration

To simplify the management of repository URLs across configuration files, the update-repo-url.sh script is provided. This script:

  1. Automatically detects your Git repository URL and current branch

  2. Updates the edit_url in antora.yml

  3. Updates the repository information in fix-edit-links.sh

Using the URL Configuration Script

Run the script before building the documentation:

./update-repo-url.sh

This ensures that both the Antora configuration and the fix-edit-links script use the same repository URL and branch, eliminating duplication and reducing the chance of errors.

When you clone the repository or switch branches, run this script to update the configuration automatically.

Customizing the Documentation Site

The MicroProfile Tutorial documentation site can be customized in various ways to enhance its appearance and functionality. Here are the key customization options:

Favicon Configuration

Favicons are configured using the supplemental-ui/partials/head-meta.hbs file, which is included in the HTML <head> section of each page. The current setup includes:

  • An SVG favicon (primary)

  • A PNG favicon (fallback for browsers that don’t support SVG)

To change the favicons:

  1. Replace the files in supplemental-ui/img/:

    • favicon.svg - Vector version of the favicon

    • favicon.png - Bitmap version of the favicon

  2. Make sure the references in head-meta.hbs match your file names

UI Customization

The UI bundle is defined in antora-assembler.yml under the ui.bundle.url key. The current configuration uses a custom UI bundle from the microprofile-documentation-ui repository.

To apply additional customizations:

  1. Add or modify files in the supplemental-ui/ directory:

    • partials/ - Override specific UI components

    • css/ - Add custom CSS styles

    • js/ - Add custom JavaScript

Common customizations include: * Tutorial Documentation: Comprehensive learning materials built with Antora and deployed as a static site * Source Code Examples: Practical MicroProfile e-commerce application code organized by chapter * Two Specialized Guides: - Contributors Guide (CONTRIBUTORS.adoc) - For documentation contributors - Developers Guide (DEVELOPERS.adoc) - For application developers

Getting Started

Depending on your goals, choose the appropriate guide:

For Contributors

If you want to contribute to the documentation or help maintain the Antora-based documentation site:

📘 Read the Contributors Guide

The Contributors Guide covers:

  • Setting up the Antora documentation site

  • Building and running the documentation locally

  • Development workflow for documentation changes

  • Understanding Antora configuration

  • Customizing the documentation site

  • Deployment and hosting options

For Developers

If you want to download and run the source code for the MicroProfile e-commerce application:

💻 Read the Developers Guide

The Developers Guide covers:

  • How to download the source code

  • Setting up your development environment

  • Building and running the code for each chapter

  • Understanding the project structure

  • Working with individual microservices

  • Common development tasks and troubleshooting

Quick Links

Documentation Contributors

  • Contributors Guide - Complete guide for documentation contributors

  • Antora Documentation - Official Antora documentation

  • modules/ROOT/pages/ - Documentation source files

  • antora-assembler.yml - Main Antora configuration file

Application Developers

Repository Structure

microprofile-tutorial/
├── CONTRIBUTORS.adoc           # Guide for documentation contributors
├── DEVELOPERS.adoc             # Guide for application developers
├── README.adoc                 # This file
├── code/                       # Source code examples by chapter
│   ├── chapter02/              # Getting Started
│   ├── chapter03/              # Persistence and Database
│   ├── chapter04/              # Configuration
│   └── ...                     # Additional chapters
├── modules/ROOT/               # Antora documentation content
│   └── pages/                  # Documentation pages
├── antora-assembler.yml        # Antora site configuration
├── antora.yml                  # Component configuration
└── build/                      # Generated documentation site (after build)

Prerequisites

For Documentation Work (Contributors)

  • Node.js (for Antora)

  • npm (comes with Node.js)

  • Antora CLI and Site Generator

See the Contributors Guide for detailed setup instructions.

For Code Development (Developers)

  • Java Development Kit (JDK) 21 or later

  • Maven 3.13 or later

  • Git

See the Developers Guide for detailed setup instructions.

Quick Start

Building the Documentation

# Install Antora (first time only)
npm install -g @antora/cli @antora/site-generator-default

# Build the documentation site
./update-repo-url.sh && antora antora-assembler.yml && ./fix-edit-links.sh

# Run locally
cd build/site && python3 -m http.server 8080

For more details, see the Contributors Guide.

Running the Code

# Clone the repository
git clone https://github.com/microprofile/microprofile-tutorial.git
cd microprofile-tutorial

# Navigate to a chapter (e.g., Chapter 2)
cd code/chapter02/mp-ecomm-store

# Run in development mode
mvn liberty:dev

For more details, see the Developers Guide.

Contributing

We welcome contributions to both the documentation and the code examples!

Please ensure your contributions follow the existing patterns and include appropriate tests or validation.

License

This project is licensed under the terms specified in the LICENSE file.

Community and Support

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

17 stars

Watchers

25 watching

Forks

6 forks
Report repository

Releases 1

6.1 Latest
Jan 22, 2026

Packages

 
 
 

Contributors

Languages