diff --git a/site/README.md b/site/README.md
index 4fc7634588a6..2df9ec207df4 100644
--- a/site/README.md
+++ b/site/README.md
@@ -52,7 +52,9 @@ To see changes in Javadoc, run:
 After site changes are committed, you can publish the site with this command:
 
 ```
-mkdocs gh-deploy
+./gradlew deploySite
 ```
 
-This assumes that the Apache remote is named `apache` and will push to the `asf-site` branch. To use a different remote add `-r <remote-name>`.
+This assumes that the Apache remote is named `apache` and will push to the
+`asf-site` branch. You can specify the name of a different remote by appending
+`-Premote.name=<remote-name>` to the `./gradlew deploySite` command.
diff --git a/tasks.gradle b/tasks.gradle
index 5758ca8cd363..9cb99c2324ae 100644
--- a/tasks.gradle
+++ b/tasks.gradle
@@ -54,6 +54,19 @@ task refreshJavadoc(type: Exec) {
 
 task deploySite(type: Exec) {
   workingDir 'site'
-  commandLine 'mkdocs', 'gh-deploy'
-}
+  def remoteName = 'apache'
+  if (project.hasProperty('remote.name')) {
+    remoteName = project.getProperty('remote.name')
+  }
 
+  // Normally the site directory is removed and built entirely from the docs
+  // directory when `mkdocs gh-deploy` runs. Removing the site directory,
+  // copying the file by hand, and using --dirty does basically the same thing,
+  // but allows us to end up with .asf.yaml in the output that gets copied to
+  // the asf-site branch. That's required for publishing now, which is why this
+  // workaround is necessary. For further clarification please see
+  // https://github.com/apache/iceberg/pull/2998#discussion_r693517612
+  commandLine('rm', '-rf', 'site')
+  commandLine('cp', '../.asf.yaml', 'site/')
+  commandLine('mkdocs', 'gh-deploy', '--dirty', '-r', remoteName)
+}