[GEODE-10650] Migrate geode-site to Pelican

.github/workflows/build-pelican.yml

@@ -0,0 +1,54 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+name: Build website
+
+on:
+  push:
+    branches: [ "master" ]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Pull requests: build only, to catch template and content errors.
+  build:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: apache/infrastructure-actions/pelican@main
+        with:
+          publish: 'false'
+          gfm: 'true'
+
+  # master: build and commit the site to the output/ directory of asf-site.
+  publish:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/master'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: 'master'
+      - uses: apache/infrastructure-actions/pelican@main
+        with:
+          destination: 'asf-site'
+          gfm: 'true'

.gitignore

@@ -1,3 +1,4 @@
-.gradle/
-/build
-/website/content/docs/guide
+/output
+__pycache__/
+*.pyc
+.venv/

.rat-excludes

@@ -0,0 +1,13 @@
+.git
+.gitignore
+.rat-excludes
+output
+LICENSE
+NOTICE
+favicon.ico
+bootstrap.min.css
+bootstrap.bundle.min.js
+fonts
+stylesheets
+docs
+releases

LICENSE

@@ -215,24 +215,12 @@ The MIT License (http://opensource.org/licenses/mit-license.html)
 
 Apache Geode bundles the following files under the MIT license:
 
-  - Bootflat v1.0.1 (http://bootflat.github.io/), Copyright (c) 2014
-    bootflat
-  - Bootstrap v3.0.0 (http://getbootstrap.com/), Copyright (c) 2011-2016
-    Twitter, Inc.
-  - Font Awesome v4.0.3 (code files) (http://fontawesome.io), Copyright (c)
-    Dave Gandy
-  - HeadJS v0.96 (http://headjs.com/), Copyright (c) 2013 Tero Piirainen
-    (tipiirai)
-  - HTML5 Shiv v3.6.2pre (https://github.com/aFarkas/html5shiv), Copyright
-    (c) 2014 Alexander Farkas (aFarkas)
-  - iCheck v0.8 (http://icheck.fronteed.com/), Copyright (c) 2013 Damir
-    Foy, http://damirfoy.com
-  - jQuery JavaScript Library v1.10.1 (https://jquery.com), Copyright (c)
-    jQuery Foundation and other contributors, http://jquery.org
-  - Normalize.css v2.1.0 (https://necolas.github.io/normalize.css/),
-    Copyright (c) Nicolas Gallagher and Jonathan Neal
-  - Respond.js v1.1.0 (https://github.com/scottjehl/Respond), Copyright (c)
-    2012 Scott Jehl
+  - Bootstrap v5.3.8, including Popper (https://getbootstrap.com/),
+    Copyright (c) 2011-2025 The Bootstrap Authors
+    (theme/geode/static/css/bootstrap.min.css,
+    theme/geode/static/js/bootstrap.bundle.min.js)
+  - Font Awesome v4.6.2 (code files) (https://fontawesome.com/v4/),
+    Copyright (c) Dave Gandy (content/stylesheets/)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -258,8 +246,8 @@ SIL Open Font License (https://opensource.org/licenses/OFL-1.1)
 
 Apache Geode bundles the following files under the SIL OFL 1.1 license:
 
-  - Font Awesome (font files) (http://fontawesome.io) Copyright (c) Dave
-    Gandy
+  - Font Awesome v4.6.2 (font files) (https://fontawesome.com/v4/),
+    Copyright (c) Dave Gandy (content/fonts/font-awesome/)
 
 Version 1.1 - 26 February 2007
 

README.md

@@ -15,171 +15,84 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-[<img src="https://geode.apache.org/img/Apache_Geode_logo.png" align="center"/>](http://geode.apache.org)
+# Apache Geode Website
 
-[![Build Status](https://travis-ci.org/apache/geode-site.svg?branch=master)](https://travis-ci.org/apache/geode-site) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0) 
+This repository contains the source of the [Apache Geode website](https://geode.apache.org).
+The site is built with [Pelican](https://getpelican.com) by the
+[ASF Infrastructure Pelican action](https://github.com/apache/infrastructure-actions/tree/main/pelican).
 
+## How publishing works
 
-# Apache Geode Site
+- The **master** branch holds the site source.
+- On every push to master, GitHub Actions builds the site and commits the result to the
+  `output/` directory of the **asf-site** branch. The ASF serves that directory as
+  https://geode.apache.org. Do not edit asf-site by hand.
+- Pull requests are built but not published, so template and content errors show up in review.
 
-This repository contains the source files for the [Apache Geode website](https://geode.apache.org). 
+## Layout
 
-The repository contains two branches:
+| Path | Contents |
+|------|----------|
+| `content/pages/` | Site pages in Markdown. `docs/index.md` becomes `/docs/`. |
+| `data/releases.yaml` | Releases shown on `/releases/` and the home page. |
+| `data/features.yaml` | Feature grid on the home page. |
+| `theme/geode/` | Jinja templates, CSS, and vendored Bootstrap. |
+| `content/docs/`, `content/releases/` | Generated user guides and API references, copied as is. |
+| `content/stylesheets/`, `content/javascripts/`, `content/fonts/`, `content/images/` | Assets used by the generated user guides. |
+| `content/schema/` | XML schemas referenced by Geode configuration files. Do not move. |
+| `content/.htaccess` | Redirects. |
+| `pelicanconf.py` | Pelican settings. |
 
-- The __master__ branch contains the site's HTML framework, composed of the top-level landing page and the next level of pages, such as Docs, Community, and Releases, and the tools needed to compile the deployable site. 
+## Build and preview locally
 
-  Content resides under the `website/content` directory. These sources are compiled into a deployable site by gradle scripts using a tool called [Pandoc](http://johnmacfarlane.net/pandoc).
+You need Python 3.10 or later.
 
-- The __asf-site__ branch contains a copy of the deployable site built from the __master__ branch, fleshed-out with __externally-generated__ content, which includes all non-framework content such as the User Guide and the Javadocs, which you build separately then add manually on the __asf-site__ branch before publishing the completed site. Stylesheets also reside on the __asf-site__ branch.
+```
+git clone https://github.com/apache/infrastructure-actions.git ../infrastructure-actions
+python3 -m venv .venv
+. .venv/bin/activate
+pip install "pelican[markdown]==4.11.0.post0" ../infrastructure-actions/pelican
+pelican content -o output -e 'PLUGIN_PATHS=["../infrastructure-actions/pelican/plugins"]' -r -l
+```
 
-  To deploy the Apache Geode website, you push the __asf-site__ branch to the upstream Apache repository. An Apache "sync" tool monitors the __asf-site__ branch 
-of the repository and publishes your update to the
-[Geode website](http://geode.apache.org) after a 5-10 minute delay.
+Open http://localhost:8000.
 
+The published site renders Markdown with GitHub Flavored Markdown (libcmark-gfm). Without it, the
+local build falls back to Pelican's standard Markdown reader, which is close enough for most
+edits. To match the published output exactly, build libcmark-gfm with
+`../infrastructure-actions/pelican/build-cmark.sh` and export the `LIBCMARKDIR` it prints before
+running `pelican`.
 
-# Update procedure
-Updating the website is a two-part process:
+## Check license headers
 
-1. On the __master__ branch, update the website's framework pages.
+Every source file needs the Apache license header. Check with
+[Apache RAT](https://creadur.apache.org/rat/) before sending a pull request:
 
-1. Check out the __asf-site__ branch and add externally-generated content, such as the User Guide and the Javadocs.
+```
+java -jar apache-rat-0.16.1.jar --dir . --exclude-file .rat-excludes
+```
 
-When the site's updated framework has been fleshed-out with external content, the site is ready to be deployed.
+`.rat-excludes` lists files that cannot carry a header: third-party code covered by `LICENSE`,
+binary images and fonts, and the generated user guides and API references.
 
-## Prerequisites
+## Common updates
 
-To generate the site locally, you need to install java and docker. 
+### Announce a release
 
-Other support tools you may need include:
+1. Add the release at the top of its line in `data/releases.yaml`.
+2. Remove any release that is no longer on https://downloads.apache.org/geode/. Older releases
+   are reached through the archive link on the page.
+3. If the release adds a new user guide, add it to `content/pages/docs/index.md`.
 
-- pandoc
-- nanoc
+### Publish a user guide
 
-## Update the website framework
+1. Build the guide as described in `geode-book/README.md` in the Geode repository.
+2. Copy it to `content/docs/guide/XY`, where `XY` is the version without dots (for example `20`
+   for 2.0). Use `tar` to preserve the directory structure.
+3. For the newest release line, replace `content/docs/guide/latest` with a copy of the same guide.
+4. Link it from `content/pages/docs/index.md`.
 
-On the __master__ branch, update the website's framework pages. For a general release, this would likely include:
-
-  - {geode-site}/website/content/index.html
-  - {geode-site}/website/content/community/index.html
-  - {geode-site}/website/content/docs/index.html
-  - {geode-site}/website/content/releases/index.html
-
-A couple of notes specific to documentation:
-
-  - The Geode website is not equipped to understand the `redirects.rb` substitutions provided with the Geode and Geode Native user guides. On this site, the file `website/content/.htaccess` provides redirect information. Edit this file on the __master__ branch, and the `gradlew publish` operation will propagate your changes to the __asf-site__ branch.
-  - If you need to change the layout or styling of the site, then you will probably need to change
-an HTML, JS or CSS file on the __asf-site__ branch.
-
-
-## Locally generate the site framework and review your changes
-
-You should still be on the __master__ branch. 
-
-1. Generate the site content by navigating to the top level directory of the `geode-site` repo and using gradle to compile the sources into a deployable site framework:
-
-    ```
-    $ ./gradlew compile
-    ```
-
-  You may need to suppress rat checking: add `-x rat` to the end of the `.gradlew` command.
-
-2. View the generated site by running:
-
-    ```
-    $ ./gradlew view
-    ```
-
-  and point your browser at `http://localhost:3000` to view the result. 
-
-  You may need to suppress rat checking: add `-x rat` to the end of the `.gradlew` command.
-
-3. To make further changes, stop the build (Ctrl-C), edit files, recompile, and view again.
-
-4. Once you are happy with your changes, commit them to the __master__ branch and push them to the upstream Apache repository.
-
-## Add externally-generated content to the site framework
-
-### 1. On the __master__ branch, run the gradle command:
-
-    $ ./gradlew publish
-
-  The gradle `publish` target:
-
-  - Checks out the __asf-site__ branch, and
-  - Copies the website files to their deployment directories.
-
-**HEADS-UP**
-The `gradlew publish` command *does not* update the `css` and `stylesheets` directories. If you made format changes there, you must manually merge the new versions of those files from the __master__ branch.
-
-  - While still on the __master__ branch, save those files to a location outside the geode-site repo.
-  - After running the `gradlew publish` command, copy the new versions to the appropriate directories in the __asf-site__ branch.
-
-
-### 2. Add a new user guide
-
-1. Create a local build of the User Guide as described in `{geode-project-dir}/geode-book/README.md`. 
-
-1. Copy the User Guide to the `geode-site` repo:
-
-  1. On the __asf-site__ branch, create a destination directory for the User Guide. The naming convention is:
-
-        ```
-        {geode-site}/docs/guide/XY
-        ```
-  where `XY` is the product version of your documentation (e.g., `{geode-site}/website/content/docs/guide/17` if you are publishing the documentation for Apache Geode 1.14). So, if your current working directory is the top level of `{geode-site}`, you would create the destination directory with the following command:
-
-        ```
-        $ mkdir -p {geode-site}/docs/guide/114
-        ```
-
-  1. Navigate to the User Guide you have built in the Geode repository: `{geode-project-dir}/geode-book/final_app/public/docs/guide/XY`.
-
-  1. Use `tar` to copy the directory in order to preserve links and other filesystem niceties.
-
-  - Create the tarfile in your Desktop for easy access on the retrieval side.
-
-        ```
-        $ tar cvf ~/Desktop/new-guide-content.tar .
-        ```
-
-  - Navigate to the target directory and un-tar the userguide archive:
-
-        ```
-        $ cd {geode-site}/docs/guide/XY
-        $ tar xvf ~/Desktop/new-guide-content.tar
-        ```
-
-  - Replace the entire `docs/guide/latest` directory with a copy of the latest user guide's directory. Use `tar` (rather than `cp`) to preserve the original directory's structure.
-
-        ```
-        $ cd {geode-site}/docs/guide
-        $ rm -rf latest
-        $ mkdir latest
-        $ cd latest
-        $ (cd ../XY && tar cf - *) | (tar xf -)
-        ```
-
-### 3. Publish new javadocs
-
-You should still be on the __asf-site__ branch. Copy new javadocs directly to the directory
-`{geode-site}/releases/latest/javadoc/`.
-
-The new javadocs _replace_ those currently within the directory.
-
-## Deploy the update
-Commit and push the __asf-site__ branch. Apache detects the update and publishes it. The site should update in 5-10 minutes.
-
-## Troubleshooting
-
-- If the site does not update in 5-10 minutes, __push a new commit by adding or subtracting a blank line in the top-level `index.html` file.__ This usually does the trick.
-
-- Check your commit of the __asf-site__ branch. The site's deployable files are at the top level, rooted at {geode-site}/index.html. Make sure that directories such as `{geode-site}/docs` and `{geode-site}/releases` contain the latest versions of `index.html` and the docs.
-
-- DO NOT commit the {geode-site}/build directory. This is the place where files compiled on the __master__ branch are placed, then retrieved after the switch to the __asf-site__ branch. It must be freshly generated with each iteration, not saved to the repo.
-
-For further assistance, you can
-
-- [file a JIRA against the INFRA project](https://issues.apache.org/jira/browse/INFRA), or 
-
-- ask for advice on the Infrastructure project's HipChat room [#asfinfra](https://www.hipchat.com/g4P84gemn).
+### Publish API documentation
 
+Replace the contents of `content/releases/latest/javadoc/` with the new Javadoc. The native client
+API references live in `content/releases/latest/cppdocs/` and `content/releases/latest/dotnetdocs/`.