Port new Download and Installation pages to 2.x (#2487)

Co-authored-by: Volkan Yazıcı <volkan@yazi.ci>

Author: ppkarwasz

antora-playbook.yaml

@@ -77,11 +77,19 @@ ui:
         <!-- `@asciidoctor/tabs` extension styles -->
         <link rel="stylesheet" href="{{{uiRootPath}}}/css/vendor/tabs.css">
         <style>
+          /* Default `h4` and `h5` are smaller than the normal text, fix header font sizing: */
+          .doc h1 { font-size: 1.9rem; }
+          .doc h2 { font-size: 1.7rem; }
+          .doc h3 { font-size: 1.5rem; font-weight: 400; }
+          .doc h4 { font-size: 1.3rem; font-weight: 500; }
+          .doc h5 { font-size: 1.1rem; font-weight: 500; text-decoration: underline; }
+          /* Tab header fonts aren't rendered good, adjusting the font weight: */
+          .tablist > ul li { font-weight: 500; } 
           /* `page-toclevels` greater than 4 are not supported by Antora UI, patching it: */
           .toc .toc-menu li[data-level="4"] a {
             padding-left: 2.75rem
           }
-          /* Replace the default highlight.js color for strings from red to green: */
+          /* Replace the default highlight.js color for strings from red (unnecessarily signaling something negative) to green: */
           .hljs-string {
             color: #0f8532;
           }

pom.xml

@@ -331,9 +331,13 @@
     <!-- Skipping `maven-site-plugin` globally. -->
     <maven.site.skip>true</maven.site.skip>
     <maven.site.deploy.skip>true</maven.site.deploy.skip>
+    <site-commons-logging.version>1.3.1</site-commons-logging.version>
+    <site-jackson.version>2.17.0</site-jackson.version>
     <site-log4j-api.version>2.23.1</site-log4j-api.version>
     <site-log4j-core.version>2.23.1</site-log4j-core.version>
     <site-log4j-layout-template-json.version>2.23.1</site-log4j-layout-template-json.version>
+    <site-logback.version>1.5.5</site-logback.version>
+    <site-slf4j.version>2.0.13</site-slf4j.version>
 
     <!-- =====================================================
          Direct dependency version properties (in alphabetical order)
@@ -672,21 +676,55 @@
              We need these `<dependency>` entries to trick `dependabot` to update the version properties automatically.
              No, we cannot use `${project.version}`, because it is not released yet. -->
         <dependencies>
+
+          <!-- Log4j component dependencies.
+               No, we cannot use `${project.version}`, because it is not released yet. -->
+
           <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-api</artifactId>
             <version>${site-log4j-api.version}</version>
           </dependency>
+
           <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-core</artifactId>
             <version>${site-log4j-core.version}</version>
           </dependency>
+
           <dependency>
             <groupId>org.apache.logging.log4j</groupId>
             <artifactId>log4j-layout-template-json</artifactId>
             <version>${site-log4j-layout-template-json.version}</version>
           </dependency>
+
+          <!-- Other dependencies -->
+
+          <dependency>
+            <groupId>commons-logging</groupId>
+            <artifactId>commons-logging</artifactId>
+            <version>${site-commons-logging.version}</version>
+          </dependency>
+
+          <dependency>
+            <groupId>com.fasterxml.jackson</groupId>
+            <artifactId>jackson-bom</artifactId>
+            <version>${site-jackson.version}</version>
+            <type>pom</type>
+          </dependency>
+
+          <dependency>
+            <groupId>ch.qos.logback</groupId>
+            <artifactId>logback-core</artifactId>
+            <version>${site-logback.version}</version>
+          </dependency>
+
+          <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>${site-slf4j.version}</version>
+          </dependency>
+
         </dependencies>
 
         <executions>

src/site/antora/antora.tmpl.yml

@@ -38,13 +38,20 @@ version: ~
 start_page: index.adoc
 asciidoc:
   attributes:
-    log4j-api-version: "${site-log4j-api.version}"
-    log4j-core-version: "${site-log4j-core.version}"
-    log4j-layout-template-json-version: "${site-log4j-layout-template-json.version}"
+    # Commons
     project-github-url: "${scm.url}"
     project-name: "Log4j"
     project-id: "log4j"
     java-target-version: "${maven.compiler.target}"
     java-compiler-version: "${minimalJavaBuildVersion}"
+    logging-services-url: "https://logging.apache.org"
+    # Dependency versions
+    commons-logging-version: "${site-commons-logging.version}"
+    jackson-version: "${site-jackson.version}"
+    log4j-api-version: "${log4j-api.version}"
+    log4j-core-version: "${site-log4j-core.version}"
+    log4j-layout-template-json-version: "${site-log4j-layout-template-json.version}"
+    logback-version: "${site-logback.version}"
+    slf4j-version: "${site-slf4j.version}"
 nav:
   - modules/ROOT/nav.adoc

src/site/antora/antora.yml

@@ -38,13 +38,20 @@ version: ~
 start_page: index.adoc
 asciidoc:
   attributes:
-    log4j-api-version: "1.2.3-api"
-    log4j-core-version: "1.2.3-core"
-    log4j-layout-template-json-version: "1.2.3-layout-template-json"
+    # Commons
     project-github-url: "https://github.com/apache/logging-log4j2"
     project-name: "Log4j"
     project-id: "log4j"
     java-target-version: "8"
     java-compiler-version: "[17,18)"
+    logging-services-url: "https://logging.apache.org"
+    # Dependency versions
+    commons-logging-version: "1.2.3-commons-logging"
+    jackson-version: "1.2.3-jackson"
+    log4j-api-version: "1.2.3-api"
+    log4j-core-version: "1.2.3-core"
+    log4j-layout-template-json-version: "1.2.3-layout-template-json"
+    logback-version: "1.2.3-logback"
+    slf4j-version: "1.2.3-slf4j"
 nav:
   - modules/ROOT/nav.adoc

src/site/antora/modules/ROOT/nav.adoc

@@ -18,12 +18,13 @@
 * xref:download.adoc[Download]
 ** xref:runtime-dependencies.adoc[]
 ** xref:release-notes.adoc[]
-* xref:support.adoc[]
-** xref:security.adoc[]
+* link:{logging-services-url}/support[Support]
+** link:{logging-services-url}/security[Security]
 ** xref:thanks.adoc[Thanks]
 
 .Learn
 * xref:manual/index.adoc[]
+** xref:manual/installation.adoc[]
 ** xref:manual/architecture.adoc[]
 ** xref:manual/migration.adoc[]
 ** xref:manual/api.adoc[]

src/site/antora/modules/ROOT/pages/download.adoc

@@ -15,234 +15,9 @@
     limitations under the License.
 ////
 
-= Install Apache Log4j
+= Download
 
-Apache Log4j is distributed under the
-https://www.apache.org/licenses/LICENSE-2.0.html[Apache License, version 2.0].
+You can manually download all published Log4j distributions, verify them, and see their licensing information by following the instructions in {logging-services-url}/download.html[the Download page] of {logging-services-url}[Logging Services].
 
-[#using-a-build-system]
-== Using a build system
-
-The preferred way to use Log4j in your project is to use a build system as Maven.
-Please add the following to your build systems configuration file `pom.xml` to use Log4j.
-
-Log4j needs two dependencies, since it is separated between the API and the Core.
-
-[tabs%sync]
-====
-Maven::
-+
-.`pom.xml` snippet
-[source,xml,subs="+attributes"]
-----
-<dependencies>
-  <dependency>
-    <groupId>org.apache.logging.log4j</groupId>
-    <artifactId>log4j-api</artifactId>
-    <version>{log4j-api-version}</version>
-  </dependency>
-  <dependency>
-    <groupId>org.apache.logging.log4j</groupId>
-    <artifactId>log4j-core</artifactId>
-    <version>{log4j-core-version}</version>
-  </dependency>
-</dependencies>
-----
-
-Gradle::
-+
-.`build.gradle` snippet
-[source,subs="+attributes"]
-----
-compile 'org.apache.logging.log4j:log4j-api:{log4j-api-version}'
-compile 'org.apache.logging.log4j:log4j-core:{log4j-core-version}'
-----
-
-Ivy::
-+
-.`ivy.xml` snippet
-[source,xml,subs="+attributes"]
-----
-<dependencies>
-  <dependency org="org.apache.logging.log4j" name="log4j-api" rev="{log4j-api-version}" />
-  <dependency org="org.apache.logging.log4j" name="log4j-core" rev="{log4j-core-version}" />
-</dependencies>
-----
-====
-
-== Bill of materials
-
-To keep your Log4j module versions in sync with each other, a BOM (Bill of Material)
-pom.xml file is provided for your convenience. To use this with https://maven.apache.org/[Maven],
-add the dependency listed below to your `pom.xml` file.
-When you specify the version identifier in this section, you don't have to specify the version in your `<dependencies/>` section.
-
-[tabs%sync]
-====
-Maven::
-+
-.`pom.xml` snippet
-[source,xml,subs="+attributes"]
-----
-<dependencyManagement>
-  <dependencies>
-    <dependency>
-      <groupId>org.apache.logging.log4j</groupId>
-      <artifactId>log4j-bom</artifactId>
-      <version>{log4j-core-version}</version>
-      <scope>import</scope>
-      <type>pom</type>
-    </dependency>
-  </dependencies>
-</dependencyManagement>
-----
-
-Gradle::
-+
-.`build.gradle` snippet
-[source,subs="+attributes"]
-----
-plugins {
-  id 'io.spring.dependency-management' version '1.0.1.RELEASE' //<1>
-}
-
-dependencyManagement {
-  imports {
-    mavenBom 'org.apache.logging.log4j:log4j-bom:{log4j-core-version}'
-  }
-}
-
-dependencies {
-  implementation 'org.apache.logging.log4j:log4j-api'
-  implementation 'org.apache.logging.log4j:log4j-core'
-  // etc.
-}
-----
-<1> The additional https://github.com/spring-gradle-plugins/dependency-management-plugin[Gradle plugin] required for dependency management functionality.
-====
-
-== Snapshot builds
-
-You can access the latest development snapshot by using the Maven repository
-`https://repository.apache.org/snapshots` and the current SNAPSHOT version.
-Generally, the master branch will use the next patch version as its snapshot
-version regardless of what the next actual version of Log4j will be. For example,
-if the latest release were `3.0`, then master would be using the version
-`3.0.1-SNAPSHOT`.
-
-To enable snapshots you'll need to enable Snapshots repositories in your build system.
-
-[tabs%sync]
-====
-Maven::
-+
-.`pom.xml` snippet
-[source,xml,subs="+attributes"]
-----
-<repositories>
-  <repository>
-    <id>apache.snapshots</id>
-    <name>Apache Snapshot Repository</name>
-    <url>https://repository.apache.org/snapshots</url>
-    <releases>
-      <enabled>false</enabled>
-    </releases>
-  </repository>
-</repositories>
-----
-
-Gradle::
-+
-.`build.gradle` snippet
-[source,subs="+attributes"]
-----
-repositories {
-  mavenCentral()
-  maven { url 'https://repository.apache.org/snapshots' }
-}
-----
-
-SBT::
-+
-.`build.sbt` snippet
-[source,subs="+attributes"]
-----
-resolvers += "Apache Snapshot Repository" at "https://repository.apache.org/snapshots"
-----
-====
-
-== Manual Download
-
-The link in the Mirrors column should display a list of available
-mirrors with a default selection based on your inferred location. If you
-do not see that page, try a different browser. The checksum and
-signature are links to the originals on the main distribution server.
-
-|===
-|Distribution |Mirrors |Checksum |Signature
-
-|Apache Log4j binary (tar.gz)
-|https://www.apache.org/dyn/closer.lua/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-bin.tar.gz[apache-log4j-{log4j-core-version}-bin.tar.gz]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-bin.tar.gz.sha512[apache-log4j-{log4j-core-version}-bin.tar.gz.sha512]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-bin.tar.gz.asc[apache-log4j-{log4j-core-version}-bin.tar.gz.asc]
-
-|Apache Log4j binary (zip)
-|https://www.apache.org/dyn/closer.lua/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-bin.zip[apache-log4j-{log4j-core-version}-bin.zip]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-bin.zip.sha512[apache-log4j-{log4j-core-version}-bin.zip.sha512]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-bin.zip.asc[apache-log4j-{log4j-core-version}-bin.zip.asc]
-
-|Apache Log4j source (tar.gz)
-|https://www.apache.org/dyn/closer.lua/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-src.tar.gz[apache-log4j-{log4j-core-version}-src.tar.gz]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-src.tar.gz.sha512[apache-log4j-{log4j-core-version}-src.tar.gz.sha512]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-src.tar.gz.asc[apache-log4j-{log4j-core-version}-src.tar.gz.asc]
-
-|Apache Log4j source (zip)
-|https://www.apache.org/dyn/closer.lua/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-src.zip[apache-log4j-{log4j-core-version}-src.zip]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-src.zip.sha512[apache-log4j-{log4j-core-version}-src.zip.sha512]
-|https://www.apache.org/dist/logging/log4j/{log4j-core-version}/apache-log4j-{log4j-core-version}-src.zip.asc[apache-log4j-{log4j-core-version}-src.zip.asc]
-|===
-
-It is essential that you verify the integrity of the downloaded files
-using the PGP or SHA512 signatures. Please read
-https://httpd.apache.org/dev/verification.html[Verifying Apache HTTP
-Server Releases] for more information on why you should verify our
-releases.
-
-The PGP signatures can be verified using PGP or GPG. First download the
-https://downloads.apache.org/logging/KEYS[KEYS] as well as the asc
-signature file for the relevant distribution. Make sure you get these
-files from the https://www.apache.org/dist/logging/[main distribution
-directory], rather than from a mirror. Then verify the signatures using
-
-[source,sh,subs=attributes,subs="+attributes"]
-----
-gpg --import KEYS
-gpg --verify apache-log4j-{log4j-core-version}-bin.zip.asc
-----
-
-Alternatively, you can verify the SHA512 signature on the files. A unix
-program called sha512sum is included in many unix distributions.
-
-[#requirements]
-== Requirements
-
-The Apache Log4j runtime requires a minimum of Java 17.
-See the http://logging.apache.org/2.x[Log4j 2 website] for the latest releases supporting Java 6, 7, and 8.
-
-== Previous Releases
-
-All previous releases of Apache log4j can be found in the
-https://archive.apache.org/dist/logging/log4j/[ASF archive repository]. Of course, all releases are availble for
-use as dependencies from the https://search.maven.org/search?q=org.apache.logging.log4j[Maven Central Repository]
-
-== Using Apache Log4j on your classpath
-
-To use Log4j in your application make sure that the API, Plugins, and Core
-jars are in the application’s classpath. Add the dependencies listed
-below to your classpath.
-
-* log4j-api-{log4j-api-version}.jar
-* log4j-plugins-{log4j-core-version}.jar
-* log4j-core-{log4j-core-version}.jar
-
-You can do this from the command line or a manifest file.
+* Are you looking for **the Log4j installation instructions**? Proceed to xref:manual/installation.adoc[].
+* Are you looking for the list of changes associated with a particular release? Proceed to xref:release-notes.adoc[].

src/site/antora/modules/ROOT/pages/index.adoc

@@ -19,15 +19,15 @@
 
 Apache Log4j is a versatile, industrial-grade Java logging framework composed of an API, its implementation,  and components to assist the deployment for various use cases.
 Log4j is https://security.googleblog.com/2021/12/apache-log4j-vulnerability.html[used by 8% of the Maven ecosystem] and listed as one of https://docs.google.com/spreadsheets/d/1ONZ4qeMq8xmeCHX03lIgIYE4MEXVfVL6oj05lbuXTDM/edit#gid=1024997528[the top 100 critical open source software projects].
-The project is actively maintained by a link:/team-list.html[team] of several volunteers and xref:support.adoc[support]ed by a big community.
+The project is actively maintained by a {logging-services-url}/team-list.html[team] of several volunteers and {logging-services-url}/support[support]ed by a big community.
 
 [#shortcuts]
 == Shortcuts
-- xref:download.adoc#using-a-build-system[How can I add Log4j artifacts to my Maven/Ivy/Gradle project?]
+- xref:manual/installation.adoc[How can I add Log4j artifacts to my Maven/Ivy/Gradle project?]
 - xref:manual/usage.adoc[How can I use the Log4j API?]
 - xref:manual/configuration.adoc[How can I configure my `log4j2.xml`?]
 - xref:release-notes.adoc[Where are the release notes?]
-- xref:support.adoc[**I need help!**]
+- {logging-services-url}/support[**I need help!**]
 
 [#features]
 == Features
@@ -45,7 +45,7 @@ API separation::
 The API for Log4j (i.e., `log4j-api`) is separate from the implementation (i.e., `log4j-core`) making it clear for application developers which classes and methods they can use while ensuring forward compatibility.
 (See xref:manual/api-separation.adoc[API Separation] for details.)
 The Log4j API also provides the most feature rich logging facade in the market; support for various `Message` types (`Object`, `Map`, etc.) besides plain `String`, lambda expressions, parametrized logging, markers, levels, diagnostic contexts (aka. MDC/NDC), etc.
-Check out the xref:manual/api.adoc[Java API], link:/log4j/kotlin[Kotlin API], and link:/log4j/scala[Scala API] pages for further information.
+Check out the xref:manual/api.adoc[Java API], {logging-services-url}/log4j/kotlin[Kotlin API], and {logging-services-url}/log4j/scala[Scala API] pages for further information.
 
 No vendor lock-in::
 Even though the Log4j API is implemented by the Log4j at its fullest, users can choose to use another logging backend.
@@ -60,3 +60,26 @@ Extensibility::
 Log4j contains a fully-fledged xref:manual/plugins.adoc[plugin support] that users can leverage to extend its functionality.
 You can easily add your own components (layouts, appenders, filters, etc.) or customizing existing ones (e.g., adding new directives to the xref:manual/layouts.adoc#PatternLayout[Pattern] or xref:manual/json-template-layout.adoc#extending[JSON Template Layout]).
 Check out the xref:manual/extending.adoc[Extending Log4j] page.
+
+[#requirements]
+== Requirements
+
+Log4j 2 runtime requires a minimum of Java 8.
+Older versions of Java are supported by previous releases.
+
+[#older-releases]
+== Older releases
+
+Are you looking for old versions of Log4j?
+While we recommend to always use the latest version, you can find the older versions here:
+
+* {logging-services-url}/1.x/[Log4j 1.x (End of Life, Java 1.4)]
+* {logging-services-url}/2.3.x/[Log4j 2.3.x (Java 6)]
+* {logging-services-url}/2.12.x/[Log4j 2.12.x (Java 7)]
+
+[#compat]
+== Compatibility
+
+The `log4j-1.2-api` module provides compatibility for applications using the Log4j 1 logging methods.
+Log4j 2 also provides support for Log4j 1 configuration files.
+See xref:manual/migration.adoc#ConfigurationCompatibility[Log4j 2 compatibility with Log4j 1] for more information.

src/site/antora/modules/ROOT/pages/manual/installation.adoc

@@ -99,9 +99,9 @@ system property `log4j2.contextSelector` to
 create a single LoggerContext using a single configuration that will be
 shared across all applications.
 2.  Place the logging jars in the container's classpath and use the
-default ClassLoaderContextSelector. Follow the
-xref:manual/webapp.adoc[instructions to initialize Log4j 2 in a web
-application]. Each application can be configured to share the same
+default ClassLoaderContextSelector.
+See the instructions shared in xref:manual/webapp.adoc[Log4j Web].
+Each application can be configured to share the same
 configuration used at the container or can be individually configured.
 If status logging is set to debug in the configuration there will be
 output from when logging is initialized in the container and then again