Getting started

Start with a local build, learn rendering in two small programs, then serve that HTML over HTTP. Afterward, choose the task guide that fits your application.

1. Clone and build locally

Clone the SimplyPages repository using its repository clone URL, or use your existing checkout. Enter the checkout directory (usually SimplyPages), then run:

java -version
./mvnw -pl simplypages install

Use JDK 21 or later for both build and runtime. The checksum-pinned Maven wrapper is the supported repository build entry point; it installs io.mindspice:simplypages:1.2.1 into your local Maven repository. GitHub release v1.2.1 provides library artifacts; this version is not published to Maven Central.

The library and repository site both target Java 21 bytecode, even when built with a later JDK. The site uses Spring Boot 4.1.1. A separate application may choose its own host; Spring is not a core rendering dependency. See build requirements and assets for the Maven/JDK pins and resource setup.

This is a controlled beta. Read the known issues and support boundaries. The current site examples default to loopback and are nondurable. Editing modes are not identity/authorization, and its chat session ownership is not authentication. Do not expose it as a production application or infer production security from its UI controls.

2. Learn rendering in two runnable programs

Render your first page: create a separate Maven project with the supplied complete POM and Java class, then inspect escaped HTML.
Render request data with slots: use the same project to render a reusable template with independent request contexts.

These lessons need no HTTP service or demo classes. They establish what a page, component, template, and render context do before adding an application host.

3. Put the HTML behind HTTP

Continue with Serve full pages and HTMX fragments inside an existing Spring MVC application. It supplies the complete controller, full-document and fragment routes, framework/WebJar asset setup, and target/swap rules. Confirm direct navigation and fragment replacement before adding features.

To browse this checkout's site and documentation instead of creating a host, run these commands from the repository root:

./build-site.sh
java -jar site/target/simplypages-site.jar

Open http://localhost:8080/docs. The site serves Markdown documentation there and built API documentation at http://localhost:8080/javadocs/index.html. The build script skips tests; it verifies packaged documentation and API inventory and bytes. The site is not the security layer required by the application recipes below, which are not installed sandbox routes.

4. Choose an application task

Build a Markdown blog: articles on disk, pagination, and ordinary/HTMX navigation.
Build a forum browser: topics and comments from ordered application data, without pretend writing actions.
Build user-editable pages: an authorized edit modal, server validation, retained drafts, and saved view updates.
Add chat: an explicitly local session transcript with a real POST composer and HTMX polling, not an LLM or durable messaging backend.
Build a dashboard: metrics, table, and cards rendered from one immutable snapshot.
Handle form submissions: validated ordinary/HTMX posts with field errors and preserved values.

Each guide states what you must already supply. In particular, the editing and form guides require real application identity and CSRF middleware; SimplyPages does not install them. Do not disable existing security to make an example run.

Existing walkthroughs

These topic URLs remain available for their longer explanations and examples:

For a bounded working edit controller with explicit security prerequisites, use Build user-editable pages. The historical 1.0.1 migration notes do not change the current checkout's 1.2.1 version or JDK 21 minimum.

Documentation home · Tutorials · How-to guides