### Small example build.maven

Source: https://hsc.aim42.org/manual/40_maven-plugin.html

Placeholder for a small example build.maven snippet. The actual content is not provided in the source.

```maven
tbd
```

--------------------------------

### Install HSC Gradle plugin (legacy)

Source: https://hsc.aim42.org/manual/30_gradle-plugin.html

Legacy installation for older Gradle setups. Uses buildscript block with repositories and classpath dependency. Note: mavenCentral and gradlePluginPortal are required; jitpack is commented out for development versions.

```groovy
buildscript {
    repositories {
        // maven { url "https://jitpack.io/" } **(1)**
        mavenCentral() **(2)**
        gradlePluginPortal() **(3)**
    }

    dependencies {
        classpath ('gradle.plugin.org.aim42:htmlSanityCheck:2.0.0-rc3') **(4)**
    }
}

apply plugin: 'org.aim42.htmlSanityCheck'
```

--------------------------------

### Basic HSC CLI example

Source: https://hsc.aim42.org/manual/20_cli.html

Runs HSC with the --sourceDir option pointing to the ./docs directory. The version placeholder <version> must be replaced with the actual version.

```bash
java -jar htmlSanityCheck-cli-<version>.jar --sourceDir ./docs
```

--------------------------------

### Install HSC Gradle plugin (default)

Source: https://hsc.aim42.org/manual/30_gradle-plugin.html

Default installation of the HSC Gradle plugin. Place inside a Gradle build file (build.gradle). Replace the version with the current release.

```groovy
plugins {
    id 'org.aim42.htmlSanityCheck' version '2.0.0-rc3' **(1)**
}
```

--------------------------------

### Extended HSC CLI example

Source: https://hsc.aim42.org/manual/20_cli.html

Runs HSC with multiple options: source directory, checking results directory, fail on errors, HTTP connection timeout, and a subset of checker classes.

```bash
java -jar htmlSanityCheck-cli-<version>.jar \
  --sourceDir ./docs \
  --checkingResultsDir ./report/htmlchecks \
  --failOnErrors true \
  --httpConnectionTimeout 1000 \
  --checkerClasses DuplicateIdChecker,MissingImageFilesChecker
```

--------------------------------

### Cache GPG password with clearsign

Source: https://hsc.aim42.org/development/publishing.html

Start the GPG agent and cache the password to avoid the batchmode error.

```bash
echo empty | gpg --clearsign -o /dev/null
```

--------------------------------

### Sign and Stage to Maven Central and Publish to GitHub

Source: https://hsc.aim42.org/development/publishing.html

Signs artifacts and loads them to Maven Central and GitHub via JReleaser. The enableSigning flag is necessary to enforce signing, which is not required for local installations or integration testing. The jreleaserRelease task implicitly calls signAll, pushes to Maven Central staging, and releases to GitHub with a tag. All steps can be rolled back.

```bash
./gradlew jreleaserRelease -PenableSigning=true -Psigning.password=... __**(1)** __**(2)**
```

--------------------------------

### curl HEAD request returning 405 (issue 219)

Source: https://hsc.aim42.org/development/design-discussions.html

Example of a HEAD request that returns HTTP 405 (Method Not Allowed) for a valid URL, causing a false negative in link checking. This motivates issue 219, which proposes a fallback to GET requests.

```bash
<snip>

curl -I https://www.amazon.de/dp/3446443487
HTTP/2 405
server: Server
content-type: text/html;charset=UTF-8

</snip>
```

--------------------------------

### Build and Test with Gradle

Source: https://hsc.aim42.org/development/publishing.html

Runs clean, check (test), and integration tests before publishing.

```bash
./gradlew clean && ./gradlew check integrationTest
```

--------------------------------

### Build documentation with generate-pages script

Source: https://hsc.aim42.org/development/documentation-build.html

Run this command in the project root to build the complete documentation using docToolchain. After execution, open public/index.html to review the results or the HSC report to check quality.

```bash
./generate-pages
```

--------------------------------

### Fallback to GET for 403/405 handling (issue 219)

Source: https://hsc.aim42.org/development/design-discussions.html

Proposed logic for handling 403 and 405 status codes: first check success codes, then fall back to a GET request and classify the final response code. This is the solution approach for issue 219.

```groovy
if (responseCode in successCodes) then return
else {

    // try GET
    connection.setRequestMethod("GET")
    int finalResponseCode = connection.getResponseCode()

    switch (realResponseCode) {
        case warningCodes: println "real warning $responseCode"; break
        case errorCodes: println "real error $responseCode"; break

        default: println "Error: Unknown or unclassified response code"
    }
}
```

--------------------------------

### Reporter.reportFindings() template method

Source: https://hsc.aim42.org/arc42/chapters/chap-08-Concepts.html

Main entry point for reporting, using the template method pattern to delegate concrete implementations to subclasses. It calls initReport, reportOverallSummary, reportAllPages, and closeReport in sequence.

```groovy
/**
 * main entry point for reporting - to be called when a report is requested
 * Uses template-method to delegate concrete implementations to subclasses
*/
    public void reportFindings() {
        initReport()            // **(1)**
        reportOverallSummary()  // **(2)**
        reportAllPages()        // **(3)**
        closeReport()           // **(4)**
    }
//
    private void reportAllPages() {
        pageResults.each { pageResult ->
            reportPageSummary( pageResult ) // **(5)**
            pageResult.singleCheckResults.each { resultForOneCheck ->
               reportSingleCheckSummary( resultForOneCheck )  // **(6)**
               reportSingleCheckDetails( resultForOneCheck )  // **(7)**
               reportPageFooter()                             // **(8)**
        }
    }

```

--------------------------------

### Enable GPG agent for signing

Source: https://hsc.aim42.org/development/publishing.html

Use the GPG Agent of your GnuPG installation to cache the secret in memory, reducing the risk of exposing the passphrase.

```bash
./gradlew -PuseGpgCmd=true <task>
```

--------------------------------

### Use GPG Agent for Signing

Source: https://hsc.aim42.org/development/publishing.html

Alternative to the previous command when GPG is configured properly, using the GPG-Agent via the useGpgCmd flag.

```bash
./gradlew jreleaserRelease -PenableSigning=true -PuseGpgCmd=true
```

--------------------------------

### Duplicate ID HTML example for DuplicateIdChecker

Source: https://hsc.aim42.org/arc42/chapters/chap-08-Concepts.html

Shows two headings with the same id attribute and a link referencing that id. The DuplicateIdChecker detects multiple definitions of the same link target.

```html
<h2 id="seealso">First Heading</h2>
<h2 id="seealso">Second Heading</h2>
<a href="#seealso">Duplicate definition - where shall I go now?</a>
```

--------------------------------

### Pass signing password via command line

Source: https://hsc.aim42.org/development/publishing.html

Provide the signing password on the command line instead of putting it in gradle.properties.

```bash
./gradlew -Psigning.password=... <task>
```

--------------------------------

### Configure Gradle signing in gradle.properties

Source: https://hsc.aim42.org/development/publishing.html

Add these entries to ${HOME}/.gradle/gradle.properties for artifact signing. Replace the keyId, secretKeyRingFile path (literal, no system properties), and password with your own values.

```properties
signing.keyId=24875D73
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
signing.password=<SECRET>
```

--------------------------------

### Anchor reference example for MissingLocalResourcesChecker

Source: https://hsc.aim42.org/arc42/chapters/chap-08-Concepts.html

Shows a local file reference combined with an internal anchor. The checker currently does not deep-check such references due to limitations (issues #252 and #253).

```html
<a href="api/Artifact.html#target">GroupInit</a>
```

--------------------------------

### Link without extension causing false positives (issue 252)

Source: https://hsc.aim42.org/development/design-discussions.html

Example of a link without an extension that causes false positives in the MissingLocalResourcesChecker (issue 252). The short form can represent multiple possible file names.

```html
<a href="/foo">
```

--------------------------------

### Login to Gradle Plugin Portal

Source: https://hsc.aim42.org/development/publishing.html

Logs in to the Gradle Plugin Portal (GPP) and stores the key and secret in ~/.gradle/gradle.properties.

```bash
./gradlew -Pprofile=gpp :htmlSanityCheck-gradle-plugin:login
```

--------------------------------

### curl HEAD request returning 301 (issue 244)

Source: https://hsc.aim42.org/development/design-discussions.html

Example of a HEAD request that returns a 301 redirect with a Location header, showing that the URL exists but has moved. This is used in issue 244 to illustrate handling of 30x status codes.

```bash
<snip>

curl -I http://www.arc.de

HTTP/1.1 301 Moved Permanently
Content-Type: text/html; charset=UTF-8
Connection: keep-alive
Keep-Alive: timeout=15
Date: Wed, 24 Oct 2018 14:16:04 GMT
Server: Apache
X-Powered-By: PHP/7.0.32
Location: https://arc42.de/
</snip>
```

--------------------------------

### Set Gradle Plugin Portal credentials as environment variables

Source: https://hsc.aim42.org/development/publishing.html

Alternative to the login command: set the GPP credentials as environment variables instead of storing them in gradle.properties.

```bash
export GRADLE_PUBLISH_KEY=...
export GRADLE_PUBLISH_SECRET=...
```

--------------------------------

### Gradle Plugin Directory Structure

Source: https://hsc.aim42.org/arc42/hsc_arc42.html

Shows the required directory layout for the Gradle plugin, including the plugin class, task class, and the properties file for the plugin descriptor.

```text
|-htmlSanityCheck
   |  |-src
   |  |  |-main
   |  |  |  |-org
   |  |  |  |  |-aim42
   |  |  |  |  |  |-htmlsanitycheck
   |  |  |  |  |  |  | ...
   |  |  |  |  |  |  |-HtmlSanityCheckPlugin.groovy // **(1)**
   |  |  |  |  |  |  |-HtmlSanityCheckTask.groovy
   |  |  |  |-resources
   |  |  |  |  |-META-INF                          // **(2)**
   |  |  |  |  |  |-gradle-plugins
   |  |  |  |  |  |  |-htmlSanityCheck.properties  // **(3)**
   |  |  |-test
   |  |  |  |-org
   |  |  |  |  |-aim42
   |  |  |  |  |  |-htmlsanitycheck
   |  |  |  |  |  |  | ...
   |  |  |  |  |  |  |-HtmlSanityCheckPluginTest
   |
```

--------------------------------

### Broken Cross Reference Example (broken.html)

Source: https://hsc.aim42.org/manual/10_manual.html

Shows an HTML snippet with a broken internal anchor link. The anchor href points to '#missing' but the bookmark id is 'missinG' (misspelled), causing a broken cross-reference. Use checkerClass _BrokenCrossReferencesChecker_ to detect this issue.

```html
<a href="#missing">internal anchor</a>
...
<h2 id="missinG">Bookmark-Header</h2>
```

--------------------------------

### HTML image tag example for MissingImageFilesChecker

Source: https://hsc.aim42.org/arc42/chapters/chap-08-Concepts.html

Shows an HTML fragment from testme.html that references an image file. The checker verifies that the referenced image file exists on the local file system, resolving the path relative to the HTML file's directory.

```html
<img src="./images/one-image.jpg">
```

--------------------------------

### Publish on Gradle Plugin Portal

Source: https://hsc.aim42.org/development/publishing.html

Publishes the plugin on the Gradle Plugin Portal. Requires GPP credentials. An additional --validate-only flag allows checking credentials. First-time publication after a maintainer change may take time due to Gradle team checks. The published version can be deleted within 7 days if subsequent steps fail.

```bash
./gradlew -Pprofile=gpp :htmlSanityCheck-gradle-plugin:publishPlugins __**(1)**
```

--------------------------------

### Publish to SDKMAN

Source: https://hsc.aim42.org/development/publishing.html

Publishes the current version to SDKMAN. Should be run after the GitHub publication because SDKMAN downloads the release from GitHub.

```bash
./gradlew jreleaserPublish
```