...
The Logging Services website is generated using JBake and Maven. The content is written in Markdown and AsciiDoc. Page layouts are written in HTML within FreeMarker template files. The HTML uses the Bootstrap framework. The website is stored in a Git repository and when you push your changes to the asf_-site branch, after a short delay, the changes will go live on the website. The beginning of this page describes how to edit the root site https://logging.apache.org. Instructions for editing project specific sites like https://logging.apache.org/log4j are towards the bottom.
Prerequisites
This page is not a tutorial. To update the website you will have to understand how JBake, Markdown and possibly HTML and Bootstrap work. Refer to the links above for documentation on those topics. You'll also need this software installed on your machine to update the website:
- Git
- Java
- Maven
Git repository layout for logging-site (https://logging.apache.org/)
|-- content <-- The automatically generated website, don't edit things here!
|
|-- sources
|
|-- pom.xml <-- Maven POM file that controls the generation
|
|-- src
|
|-- main
|
|-- jbake
|
|-- assets <-- Static files to be copied into the generated website
|
|-- content <-- One markdown or asciidoc page for each page of the website
|
|-- templates <-- Freemarker templates for website HTML layout
Steps to update the logging-site (https://logging.apache.org/) website
Use Git to clone the roller-website repo, for example:
git clone https://gitbox.apache.org/repos/asf/logging-site.git
Make sure you are on the asf-staging branch:
cd logging-site
git checkout asf-staging
Make your changes to Markdowna (.md) and FreeMarker (.ftl) files under the source directory.
Generate the website via Maven. Running mvn install will generate the website into the content directory.
cd sources
mvn install
You can then view them in your browser by opening content/index.html. Or alternatively, run
mvn jbake:inline
so you can view the website locally at http://localhost:8080Once the site looks good, commit your changes and preview them in the staging environment.
git add *
git commit -m "my wonderful changes" .git push origin asf-staging
Pushing your changes will cause the ASF website infrastructure will pick up your changes and publish them to the logging.staged.apache.org web site.
Once the changes have been verified checkout the asf-site branch and update the asf-site branch to include your changes.
Code Block git checkout asf-site git rebase asf-staging
Publish the site
Code Block git push origin asf-site
- The changes to the site should be published shortly.
Prepare asf-staging for the next update
Code Block git checkout asf-staging git rebase asf-site git push origin asf-staging
Updating Logging Services Project Web Sites
Each Logging Services Project provides its own web site in its own Git repository:
To update the site for a new sub project
- Clone the appropriate repository.
- Checkout the asf-staging branch.
- Add the new site under the content directory (or a subdirectory of that as appropriate).
- Update the "latest" symlink to reference the new directory that was just added.
Commit the changes.
Code Block git add * git commit -m "my wonderful changes" . git push origin asf-staging
- Review the changes at https://logging.staged.apache.org/project/latest, replacing "latest" with the name of the symlink used by the sub-project.
Once the changes are approved publish them on the live site
Code Block git checkout asf-site git rebase asf-staging git push origin asf-site
Deeper dive into updating logging-log4j-site (https://logging.apache.org/log4j/2.x/)
Overview of how a specific release becomes the default content on https://logging.apache.org/log4j
- /index.html contains <meta http-equiv="Refresh" content="0; URL=https://logging.apache.org/log4j/2.x/">
- /2.x is a symbolic link that maps to log4j-2.17.0
- /log4j-2.17.0 contains release specific index.html, security.html
Example of how to access older content: https://logging.apache.org/log4j/log4j-2.12.2/
In order to update HTML files the site must be generated via Maven from the logging-log4j2 then the generated html and other content copied into logging-log4j-site. Its common for individually changed HTML files to be copied into logging-log4j-site, not necessarily the entire site.
- Clone the release-2.x branch of https://github.com/apache/logging-log4j2.git then run "mvn clean site -DskipTests" to generate the full site which includes all the appender specific documentation; the command takes about an hour to run on modern 2020/2021 hardware.
- Clone the asf-staging branch of https://github.com/apache/logging-log4j-site
- Copy the generated html files from logging-log4j2's /target/site to a release specific folder in a release folder in logging-log4j2-site, for example /log4j-2.12.3
- Changes made in https://github.com/apache/logging-log4j2/tree/release-2.x/src/site/markdown will be carried forward to future releases
- To make documentation changes to past releases like 2.12.3 run the "mvn site" command from a specific tag like https://github.com/apache/logging-log4j2/tree/log4j-2.12.3-rc1 then copy changed files to the matching folder in logging-log4j-site
- If you're editing one of the main files in logging-log4j2's /src/site/markdown folder (articles.md, index.md.vm, security.md, etc) "mvn site" can be made significantly faster (completes in about a minute on modern 2020/2021 hardware) by temporarily removing (do not commit commented out code!) the ~34 <module> nodes in https://github.com/apache/logging-log4j2/blob/release-2.x/pom.xml
- Follow the instructions to push to asf-staging then asf-site