diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 3f3b10f1dcbcd..daab509afbfd6 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -35,7 +35,15 @@ repos:
       - id: doctoc
         name: Add TOC for Markdown and RST files
         files:
-          ^README\.md$|^UPDATING.*\.md$|^chart/UPDATING.*\.md$|^dev/.*\.md$|^dev/.*\.rst$|^\.github/.*\.md|^airflow-core/tests/system/README\.md$
+          (?x)
+          ^README\.md$|
+          ^UPDATING.*\.md$|
+          ^chart/UPDATING.*\.md$|
+          ^dev/.*\.md$|
+          ^dev/.*\.rst$|
+          ^docs/README\.md$|
+          ^\.github/.*\.md$|
+          ^airflow-core/tests/system/README\.md$
         args:
           - "--maxlevel"
           - "2"
@@ -479,7 +487,10 @@ repos:
         name: Generate airflow diagrams
         entry: ./scripts/ci/pre_commit/generate_airflow_diagrams.py
         language: python
-        files: ^airflow-core/docs/.*/diagram_[^/]*\.py$
+        files: >
+          (?x)
+          ^airflow-core/docs/.*/diagram_[^/]*\.py$|
+          ^docs/images/.*\.py$
         pass_filenames: true
         additional_dependencies: ['rich>=12.4.4', 'diagrams>=0.23.4']
       - id: generate-volumes-for-sources
diff --git a/apache_airflow_site.py b/apache_airflow_site.py
new file mode 100644
index 0000000000000..13a83393a9124
--- /dev/null
+++ b/apache_airflow_site.py
@@ -0,0 +1,16 @@
+# 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.
diff --git a/dev/README_RELEASE_AIRFLOW.md b/dev/README_RELEASE_AIRFLOW.md
index 9998162763b5f..2e49942705dbc 100644
--- a/dev/README_RELEASE_AIRFLOW.md
+++ b/dev/README_RELEASE_AIRFLOW.md
@@ -43,7 +43,6 @@
   - [Manually prepare production Docker Image](#manually-prepare-production-docker-image)
   - [Verify production images](#verify-production-images)
   - [Publish documentation](#publish-documentation)
-  - [Wait and make sure documentation is published on the website before proceeding](#wait-and-make-sure-documentation-is-published-on-the-website-before-proceeding)
   - [Notify developers of release](#notify-developers-of-release)
   - [Send announcements about security issues fixed in the release](#send-announcements-about-security-issues-fixed-in-the-release)
   - [Add release data to Apache Committee Report Helper](#add-release-data-to-apache-committee-report-helper)
@@ -819,53 +818,33 @@ breeze prod-image verify --image-name apache/airflow:${VERSION}
 ## Publish documentation
 
 Documentation is an essential part of the product and should be made available to users.
-In our cases, documentation for the released versions is published in a separate repository - [`apache/airflow-site`](https://github.com/apache/airflow-site), but the documentation source code and build tools are available in the `apache/airflow` repository, so you have to coordinate between the two repositories to be able to build the documentation.
+In our cases, documentation for the released versions is published in S3 bucket, and the site is
+kept in a separate repository - [`apache/airflow-site`](https://github.com/apache/airflow-site),
+but the documentation source code and build tools are available in the `apache/airflow` repository, so
+you need to run several workflows to publish the documentation. More details about it can be found in
+[Docs README](../docs/README.md) showing the architecture and workflows including manual workflows for
+emergency cases.
 
-Documentation for providers can be found in the ``/docs/apache-airflow`` directory.
+There are two steps to publish the documentation:
 
-- First, copy the airflow-site repository and set the environment variable ``AIRFLOW_SITE_DIRECTORY``.
+1. Publish the documentation to S3 bucket.
 
-    ```shell script
-    git clone https://github.com/apache/airflow-site.git airflow-site
-    cd airflow-site
-    git checkout -b ${VERSION}-docs
-    export AIRFLOW_SITE_DIRECTORY="$(pwd)"
-    ```
-
-- Then you can go to the directory and build the necessary documentation packages
-
-    ```shell script
-    cd "${AIRFLOW_REPO_ROOT}"
-    breeze build-docs apache-airflow docker-stack --clean-build
-    ```
+The release manager publishes the documentation using GitHub Actions workflow
+[Publish Docs to S3](https://github.com/apache/airflow/actions/workflows/publish-docs-to-s3.yml).
 
-- Now you can preview the documentation.
+You can specify the tag to use to build the docs and 'apache-airflow docker-stack' passed as packages to be
+built.
 
-    ```shell script
-    ./docs/start_doc_server.sh
-    ```
-
-- Copy the documentation to the ``airflow-site`` repository, create commit, push changes, open a PR and merge it when the build is green.
-
-    ```shell script
-    breeze release-management publish-docs apache-airflow docker-stack
-    breeze release-management add-back-references apache-airflow --airflow-site-directory "${AIRFLOW_SITE_DIRECTORY}"
-    breeze sbom update-sbom-information --airflow-version ${VERSION} --airflow-site-directory ${AIRFLOW_SITE_DIRECTORY} --force --all-combinations --run-in-parallel
-    cd "${AIRFLOW_SITE_DIRECTORY}"
-    git add .
-    git commit -m "Add documentation for Apache Airflow ${VERSION}"
-    git push
-    # and finally open a PR
-    ```
+After that step, the provider documentation should be available under the usual urls (same as in PyPI packages)
+but stable links and drop-down boxes should not be updated.
 
-The `--run-in-parallel` switch allows to speed up SBOM generation significantly, but it might take a lot
-of memory - if you are running into memory issues you can limit parallelism by setting `--parallelism N`
-where N is a number of parallel `cdxgen` servers that should be started.
+2. Update version drop-down and stable links with the new versions of the documentation.
 
-## Wait and make sure documentation is published on the website before proceeding
+In order to do it, you need to run the [Build docs](https://github.com/apache/airflow-site/actions/workflows/build.yml)
+workflow in `airflow-site` repository.
 
-This is important as it takes time for the documentation to be published. You should exercise some patient
-here before proceeding with the next steps.
+After that workflow completes, the new version should be available in the drop-down list and stable links
+should be updated.
 
 
 ## Notify developers of release
diff --git a/dev/README_RELEASE_HELM_CHART.md b/dev/README_RELEASE_HELM_CHART.md
index 94234db7a2c8a..83e8f0c12127f 100644
--- a/dev/README_RELEASE_HELM_CHART.md
+++ b/dev/README_RELEASE_HELM_CHART.md
@@ -686,62 +686,34 @@ git push apache helm-chart/${VERSION}
 
 ## Publish documentation
 
-In our cases, documentation for the released versions is published in a separate repository -
-[`apache/airflow-site`](https://github.com/apache/airflow-site), but the documentation source code and
-build tools are available in the `apache/airflow` repository, so you have to coordinate
-between the two repositories to be able to build the documentation.
-
-- First, copy the airflow-site repository, create branch, and set the environment variable ``AIRFLOW_SITE_DIRECTORY``.
-
-    ```shell
-    git clone https://github.com/apache/airflow-site.git airflow-site
-    cd airflow-site
-    git checkout -b helm-${VERSION}-docs
-    export AIRFLOW_SITE_DIRECTORY="$(pwd -P)"
-    ```
-
-- Then you can go to the directory and build the necessary documentation packages
-
-    ```shell
-    cd "${AIRFLOW_REPO_ROOT}"
-    git checkout helm-chart/${VERSION}
-    breeze build-docs helm-chart --clean-build
-    ```
-
-- Now you can preview the documentation.
-
-    ```shell
-    ./docs/start_doc_server.sh
-    ```
-
-- Copy the documentation to the ``airflow-site`` repository.
-
-    ```shell
-    breeze release-management publish-docs helm-chart
-    ```
-
-- Update `index.yaml`
-
-  Regenerate `index.yaml` so it can be added to the Airflow website to allow: `helm repo add apache-airflow https://airflow.apache.org`.
-
-    ```shell
-    breeze release-management add-back-references helm-chart
-    cd "${AIRFLOW_SITE_DIRECTORY}"
-    curl https://dist.apache.org/repos/dist/dev/airflow/helm-chart/${VERSION}${VERSION_SUFFIX}/index.yaml -o index.yaml
-    cp ${AIRFLOW_SVN_RELEASE_HELM}/${VERSION}/airflow-${VERSION}.tgz .
-    helm repo index --merge ./index.yaml . --url "https://downloads.apache.org/airflow/helm-chart/${VERSION}"
-    rm airflow-${VERSION}.tgz
-    mv index.yaml landing-pages/site/static/index.yaml
-    ```
-
-- Commit new docs, push, and open PR
-
-    ```shell
-    git add .
-    git commit -m "Add documentation for Apache Airflow Helm Chart ${VERSION}"
-    git push
-    # and finally open a PR
-    ```
+Documentation is an essential part of the product and should be made available to users.
+In our cases, documentation for the released versions is published in S3 bucket, and the site is
+kept in a separate repository - [`apache/airflow-site`](https://github.com/apache/airflow-site),
+but the documentation source code and build tools are available in the `apache/airflow` repository, so
+you need to run several workflows to publish the documentation. More details about it can be found in
+[Docs README](../docs/README.md) showing the architecture and workflows including manual workflows for
+emergency cases.
+
+There are two steps to publish the documentation:
+
+1. Publish the documentation to S3 bucket.
+
+The release manager publishes the documentation using GitHub Actions workflow
+[Publish Docs to S3](https://github.com/apache/airflow/actions/workflows/publish-docs-to-s3.yml).
+
+You can specify the tag to use to build the docs and 'helm-chart' passed as packages to be built.
+
+After that step, the provider documentation should be available under the usual urls (same as in PyPI packages)
+but stable links and drop-down boxes should not be updated.
+
+2. Update version drop-down and stable links with the new versions of the documentation.
+
+In order to do it, you need to run the [Build docs](https://github.com/apache/airflow-site/actions/workflows/build.yml)
+workflow in `airflow-site` repository.
+
+After that workflow completes, the new version should be available in the drop-down list and stable links
+should be updated.
+
 
 ## Notify developers of release
 
diff --git a/dev/README_RELEASE_PROVIDERS.md b/dev/README_RELEASE_PROVIDERS.md
index 190cd2f11129e..014750550fc6f 100644
--- a/dev/README_RELEASE_PROVIDERS.md
+++ b/dev/README_RELEASE_PROVIDERS.md
@@ -37,7 +37,6 @@
   - [Commit the source packages to Apache SVN repo](#commit-the-source-packages-to-apache-svn-repo)
   - [Publish the Regular convenience package to PyPI](#publish-the-regular-convenience-package-to-pypi)
   - [Add tags in git](#add-tags-in-git)
-  - [Prepare documentation](#prepare-documentation)
   - [Prepare issue in GitHub to keep status of testing](#prepare-issue-in-github-to-keep-status-of-testing)
   - [Prepare voting email for Providers release candidate](#prepare-voting-email-for-providers-release-candidate)
   - [Verify the release candidate by PMC members](#verify-the-release-candidate-by-pmc-members)
@@ -46,8 +45,8 @@
   - [Summarize the voting for the Apache Airflow release](#summarize-the-voting-for-the-apache-airflow-release)
   - [Publish release to SVN](#publish-release-to-svn)
   - [Publish the packages to PyPI](#publish-the-packages-to-pypi)
-  - [Publish documentation prepared before](#publish-documentation-prepared-before)
   - [Add tags in git](#add-tags-in-git-1)
+  - [Publish documentation](#publish-documentation)
   - [Update providers metadata](#update-providers-metadata)
   - [Notify developers of release](#notify-developers-of-release)
   - [Send announcements about security issues fixed in the release](#send-announcements-about-security-issues-fixed-in-the-release)
@@ -486,137 +485,6 @@ If you want to disable this behaviour, set the env **CLEAN_LOCAL_TAGS** to false
 breeze release-management tag-providers
 ```
 
-## Prepare documentation
-
-Documentation is an essential part of the product and should be made available to users.
-In our cases, documentation  for the released versions is published in a separate repository -
-[`apache/airflow-site`](https://github.com/apache/airflow-site), but the documentation source code
-and build tools are available in the `apache/airflow` repository, so you have to coordinate between
-the two repositories to be able to build the documentation.
-
-Documentation for providers can be found in the `/docs/apache-airflow-providers` directory
-and the `/docs/apache-airflow-providers-*/` directory. The first directory contains the package contents
-lists and should be updated every time a new version of Provider distributions is released.
-
-- First, copy the airflow-site repository and set the environment variable ``AIRFLOW_SITE_DIRECTORY``.
-
-```shell script
-git clone https://github.com/apache/airflow-site.git airflow-site
-cd airflow-site
-export AIRFLOW_SITE_DIRECTORY="$(pwd -P)"
-```
-
-Note if this is not the first time you clone the repo make sure main branch is rebased:
-
-```shell script
-cd "${AIRFLOW_SITE_DIRECTORY}"
-git checkout main
-git pull --rebase
-```
-
-- Then you can go to the directory and build the necessary documentation packages
-
-```shell script
-cd "${AIRFLOW_REPO_ROOT}"
-breeze build-docs --clean-build apache-airflow-providers all-providers --include-removed-providers --include-commits
-```
-
-Usually when we release packages we also build documentation for the "documentation-only" packages. This
-means that unless we release just few selected packages or if we need to deliberately skip some packages
-we should release documentation for all Provider distributions and the above command is the one to use.
-
-If we want to just release some providers you can release them using package names:
-
-```shell script
-cd "${AIRFLOW_REPO_ROOT}"
-breeze build-docs apache-airflow-providers cncf.kubernetes sftp --clean-build --include-commits
-```
-
-Alternatively, if you have set the environment variable: `DISTRIBUTIONS_LIST` above, just run the command:
-
-```shell script
-cd "${AIRFLOW_REPO_ROOT}"
-breeze build-docs --clean-build --include-commits
-```
-
-Or using `--distributions-list` argument:
-
-```shell script
-breeze build-docs --distributions-list PACKAGE1,PACKAGE2 --include-commits
-```
-
-- Now you can preview the documentation.
-
-```shell script
-./docs/start_doc_server.sh
-```
-
-If you encounter error like:
-
-```shell script
-airflow git:(main) ./docs/start_doc_server.sh
-./docs/start_doc_server.sh: line 22: cd: /Users/eladkal/PycharmProjects/airflow/docs/_build: No such file or directory
-```
-
-That probably means that the doc folder is empty thus it can not build the doc server.
-This indicates that previous step of building the docs did not work.
-
-- Copy the documentation to the ``airflow-site`` repository
-
-All providers (including overriding documentation for doc-only changes) - note that publishing is
-way faster on multi-cpu machines when you are publishing multiple providers:
-
-
-```shell script
-cd "${AIRFLOW_REPO_ROOT}"
-
-breeze release-management publish-docs apache-airflow-providers all-providers --include-removed-providers \
-    --override-versioned --run-in-parallel
-
-breeze release-management add-back-references all-providers
-```
-
-If you have providers as list of provider ids because you just released them you can build them with
-
-```shell script
-cd "${AIRFLOW_REPO_ROOT}"
-
-breeze release-management publish-docs amazon apache.beam google ....
-breeze release-management add-back-references all-providers
-```
-
-Alternatively, if you have set the environment variable: `DISTRIBUTIONS_LIST` above, just run the command:
-
-```shell script
-breeze release-management publish-docs
-breeze release-management add-back-references all-providers
-```
-
-Or using `--distributions-list` argument:
-
-```shell script
-breeze release-management publish-docs --distributions-list PACKAGE1,PACKAGE2
-breeze release-management add-back-references all-providers
-```
-
-
-Review the state of removed, suspended, new packages in
-[the docs index](https://github.com/apache/airflow-site/blob/master/landing-pages/site/content/en/docs/_index.md):
-
-- If you publish a new package, you must add it to the list of packages in the index.
-- If there are changes to suspension or removal status of a package  you must move it appropriate section.
-
-- Create the commit and push changes.
-
-```shell script
-cd "${AIRFLOW_SITE_DIRECTORY}"
-branch="add-documentation-$(date "+%Y-%m-%d%n")"
-git checkout -b "${branch}"
-git add .
-git commit -m "Add documentation for packages - $(date "+%Y-%m-%d%n")"
-git push --set-upstream origin "${branch}"
-```
-
 ## Prepare issue in GitHub to keep status of testing
 
 Create a GitHub issue with the content generated via manual execution of the command below. You will use
@@ -1253,21 +1121,6 @@ Copy links to updated packages, sort it alphabetically and save it on the side.
 
 * Again, confirm that the packages are available under the links printed.
 
-## Publish documentation prepared before
-
-Merge the PR that you prepared before with the documentation.
-
-If you decided to remove some packages from the release make sure to do amend the commit in this way:
-
-* find the packages you removed in `docs-archive/apache-airflow-providers-<PROVIDER>`
-* remove the latest version (the one you were releasing)
-* update `stable.txt` to the previous version
-* in the (unlikely) event you are removing first version of package:
-   * remove whole `docs-archive/apache-airflow-providers-<PROVIDER>` folder
-   * remove package from `docs-archive/apache-airflow-providers/core-extensions/index.html` (2 places)
-   * remove package from `docs-archive/apache-airflow-providers/core-extensions/connections.html` (2 places)
-   * remove package from `docs-archive/apache-airflow-providers/core-extensions/extra-links.html` (2 places)
-   * remove package from `docs-archive/apache-airflow-providers/core-extensions/packages-ref.html` (5 places)
 
 ## Add tags in git
 
@@ -1283,6 +1136,61 @@ If you want to disable this behaviour, set the env **CLEAN_LOCAL_TAGS** to false
 breeze release-management tag-providers
 ```
 
+## Publish documentation
+
+Documentation is an essential part of the product and should be made available to users.
+In our cases, documentation for the released versions is published in S3 bucket, and the site is
+kept in a separate repository - [`apache/airflow-site`](https://github.com/apache/airflow-site),
+but the documentation source code and build tools are available in the `apache/airflow` repository, so
+you need to run several workflows to publish the documentation. More details about it can be found in
+[Docs README](../docs/README.md) showing the architecture and workflows including manual workflows for
+emergency cases.
+
+There are two steps to publish the documentation:
+
+1. Publish the documentation to S3 bucket.
+
+The release manager publishes the documentation using GitHub Actions workflow
+[Publish Docs to S3](https://github.com/apache/airflow/actions/workflows/publish-docs-to-s3.yml).
+
+You can specify the tag to use to build the docs and list of providers to publish (separated by spaces) or
+``all-providers`` in case you want to publish all providers (optionally you can exclude
+some of those providers)
+
+After that step, the provider documentation should be available under the usual urls (same as in PyPI packages)
+but stable links and drop-down boxes should not be updated.
+
+Use "live" S3 to publish the final documentation.
+
+2. Update version drop-down and stable links with the new versions of the documentation.
+
+Before doing it - review the state of removed, suspended, new packages in
+[the docs index](https://github.com/apache/airflow-site/blob/master/landing-pages/site/content/en/docs/_index.md):
+
+- If you publish a new package, you must add it to the list of packages in the index.
+- If there are changes to suspension or removal status of a package  you must move it appropriate section.
+
+- In case you need to make any changes - create the commit and push changes and merge it to main branch.
+  in [airflow-site](https://github.com/apache/airflow-site) repository.
+
+```shell script
+cd "${AIRFLOW_SITE_DIRECTORY}"
+branch="add-documentation-$(date "+%Y-%m-%d%n")"
+git checkout -b "${branch}"
+git add .
+git commit -m "Add documentation for packages - $(date "+%Y-%m-%d%n")"
+git push --set-upstream origin "${branch}"
+```
+
+Merging the PR with the index changes to main will trigger site publishing.
+
+If you do not need to merge a PR, you can manually run the
+[Build docs](https://github.com/apache/airflow-site/actions/workflows/build.yml)
+workflow in `airflow-site` repository.
+
+After that build from PR or workflow completes, the new version should be available in the drop-down
+list and stable links should be updated.
+
 ## Update providers metadata
 
 ```shell script
diff --git a/docs/README.md b/docs/README.md
index e9469e03786b7..7654e64270a3d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -17,6 +17,23 @@
  under the License.
  -->
 
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of contents**
+
+- [Documentation configuration](#documentation-configuration)
+- [Architecture of documentation for Airflow](#architecture-of-documentation-for-airflow)
+- [Diagrams of the documentation architecture](#diagrams-of-the-documentation-architecture)
+- [Typical workflows](#typical-workflows)
+  - [Publishing the documentation by the release manager](#publishing-the-documentation-by-the-release-manager)
+  - [Publishing changes to the website (including theme)](#publishing-changes-to-the-website-including-theme)
+- [Fixing historical documentation](#fixing-historical-documentation)
+  - [Manually publishing documentation directly to S3](#manually-publishing-documentation-directly-to-s3)
+  - [Manually publishing documentation via `apache-airflow-site-archive` repo](#manually-publishing-documentation-via-apache-airflow-site-archive-repo)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+
 # Documentation configuration
 
 This directory used to contain all the documentation files for the project. The documentation has
@@ -37,3 +54,197 @@ Documentation for general overview and summaries not connected with any specific
 
 * `docker-stack-docs` - documentation for Docker Stack'
 * `providers-summary-docs` - documentation for provider summary page
+
+# Architecture of documentation for Airflow
+
+Building documentation for Airflow is optimized for speed and for convenience workflows of the release
+managers and committers who publish and fix the documentation - that's why it's a little complex, as we have
+multiple repositories and multiple sources of the documentation involved.
+
+There are few repositories under `apache` organization which are used to build the documentation for Airflow:
+
+* `apache-airflow` - the repository with the code and the documentation sources for Airflow distributions,
+   provider distributions, providers summary and docker summary: [apache-airflow](https://github.com/apache/airflow)
+   from here we publish the documentation to S3 bucket where the documentation is hosted.
+* `airflow-site` - the repository with the website theme and content where we keep sources of the website
+   structure, navigation, theme for the website [airflow-site](https://github.com/apache/airflow). From here
+   we publish the website to the ASF servers so they are publish as the [official website](https://airflow.apache.org)
+* `airflow-site-archive` - here we keep the archived historical versions of the generated documentation
+   of all the documentation packages that we keep on S3. This repository is automatically synchronized from
+   the S3 buckets and is only used in case we need to perform a bulk update of historical documentation. Here only
+   generated `html`, `css`, `js` and `images` files are kept, no sources of the documentation are kept here.
+
+We have two S3 buckets where we can publish the documentation generated from `apache-airflow` repository:
+
+* `s3://live-docs-airflow-apache-org/docs/` - live, [official documentation](https://airflow.apache.org/docs/)
+* `s3://staging-docs-airflow-apache-org/docs/` - staging documentation [official documentation](https://staging-airflow.apache.org/docs/) TODO: make it work
+
+# Diagrams of the documentation architecture
+
+This is the diagram of live documentation architecture:
+
+![Live documentation architecture](images/documentation_architecture.png)
+
+Staging documentation architecture is similar, but uses staging bucket and staging Apache Website.
+
+# Typical workflows
+
+There are a few typical workflows that we support:
+
+## Publishing the documentation by the release manager
+
+The release manager publishes the documentation using GitHub Actions workflow
+[Publish Docs to S3](https://github.com/apache/airflow/actions/workflows/publish-docs-to-s3.yml).
+The same workflow can be used to publish Airflow, Helm chart and providers documentation.
+
+The person who triggers the build (release manager) should specify the tag name of the docs to be published
+and the list of documentation packages to be published. Usually it is:
+
+* Airflow: `apache-airflow docker-stack` (later we will add `airflow-ctl` and `task-sdk`)
+* Helm chart: `helm-chart`
+* Providers: `provider_id1 provider_id2` or `all providers` if all providers should be published.
+
+Optionally - specifically if we run `all-providers` and release manager wants to exclude some providers,
+they can specify documentation packages to exclude. Leaving "no-docs-excluded" will publish all packages
+specified to be published without exclusions.
+
+You can also specify whether "live" or "staging" documentation should be published. The default is "live".
+
+Example screenshot of the workflow triggered from the GitHub UI:
+
+![Publishing airflow or providers](images/publish_airflow.png)
+
+Note that this just publishes the documentation but does not update the "site" with version numbers or
+stable links to providers and airflow - if you release a new documentation version it will be available
+with direct URL (say https://apache.airflow.org/docs/apache-airflow/3.0.1/) but the main site will still
+point to previous version of the documentation as `stable` and the version drop-downs will not be updated.
+
+In order to do it, you need to run the [Build docs](https://github.com/apache/airflow-site/actions/workflows/build.yml)
+workflow in `airflow-site` repository. This will build the website and publish it to the `publish`
+branch of `airflow-site` repository, including refreshing of the version numbers in the drop-downs and
+stable links.
+
+![Publishing site](images/publish_site.png)
+
+
+Some time after the workflow succeeds and documentation is published, in live bucket, the `airflow-site-archive`
+repository is automatically synchronized with the live S3 bucket. TODO: IMPLEMENT THIS, FOR NOW IT HAS
+TO BE MANUALLY SYNCHRONIZED VIA [Sync s3 to GitHub](https://github.com/apache/airflow-site-archive/actions/workflows/s3-to-github.yml)
+workflow in `airflow-site-archive` repository. The `airflow-site-archive` essentially keeps the history of
+snapshots of the `live` documentation.
+
+## Publishing changes to the website (including theme)
+
+The workflows in `apache-airflow` only update the documentation for the packages (Airflow, Helm chart,
+Providers, Docker Stack) that we publish from airflow sources. If we want to publish changes to the website
+itself or to the theme (css, javascript) we need to do it in `airflow-site` repository.
+
+Publishing of airflow-site happens automatically when a PR from `airflow-site` is merged to `main` or when
+the [Build docs](https://github.com/apache/airflow-site/actions/workflows/build.yml) workflow is triggered
+manually in the main branch of `airflow-site` repository. The workflow builds the website and publishes it to
+`publish` branch of `airflow-site` repository, which in turn gets picked up by the ASF servers and is
+published as the official website. This includes any changes to `.htaccess` of the website.
+
+Such a main build also publishes latest "sphinx-airflow-theme" package to GitHub so that the next build
+of documentation can automatically pick it up from there. This means that if you want to make changes to
+`javascript` or `css` that are part of the theme, you need to do it in `ariflow-site` repository and
+merge it to `main` branch in order to be able to run the documentation build in `apache-airflow` repository
+and pick up the latest version of the theme.
+
+The version of sphinx theme is fixed in both repositories:
+
+* https://github.com/apache/airflow-site/blob/main/sphinx_airflow_theme/sphinx_airflow_theme/__init__.py#L21
+* https://github.com/apache/airflow/blob/main/devel-common/pyproject.toml#L77 in "docs" section
+
+In case of bigger changes to the theme, we
+can first iterate on the website and merge a new theme version, and only after that we can switch to the new
+version of the theme.
+
+
+# Fixing historical documentation
+
+Sometimes we need to update historical documentation (modify generated `html`) - for example when we find
+bad links or when we change some of the structure in the documentation. This can be done via the
+`airflow-site-archive` repository. The workflow is as follows:
+
+1. Get the latest version of the documentation from S3 to `airflow-site-archive` repository using
+   `Sync s3 to GitHub` workflow. This will download the latest version of the documentation from S3 to
+   `airflow-site-archive` repository (this should be normally not needed, if automated synchronization works).
+2. Make the changes to the documentation in `airflow-site-archive` repository. This can be done using any
+   text editors, scripts etc. Those files are generated as `html` files and are not meant to be regenerated,
+   they should be modified as `html` files in-place
+3. Commit the changes to `airflow-site-archive` repository and push them to `some` branch of the repository.
+4. Run `Sync GitHub to S3` workflow in `airflow-site-archive` repository. This will upload the modified
+   documentation to S3 bucket.
+5. You can choose, whether to sync the changes to `live` or `staging` bucket. The default is `live`.
+6. By default the workflow will synchronize all documentation modified in single - last commit pushed to
+   the branch you specified. You can also specify "full_sync" to synchronize all files in the repository.
+7. In case you specify "full_sync", you can also synchronize `all` docs or only selected documentation
+   packages (for example `apache-airflow` or `docker-stack` or `amazon` or `helm-chart`) - you can specify
+   more than one package separated by  spaces.
+8. After you synchronize the changes to S3, the Sync `S3 to GitHub` workflow will be triggered
+   automatically and the changes will be synchronized to `airflow-site-archive` `main` branch - so there
+   is no need to merge your changes to `main` branch of `airflow-site-archive` repository. You can safely
+   delete the branch you created in step 3.
+
+![Sync GitHub to S3](images/sync_github_to_s3.png)
+
+
+## Manually publishing documentation directly to S3
+
+The regular publishing workflows involve running Github Actions workflow and they cover majority of cases,
+however sometimes some manual updates and cherry-picks are needed, when we discover problems with the
+publishing and doc building code - for example when we find that we need to fix extensions to sphinx.
+
+In such case, release manager or a committer can build and publish documentation locally - providing that
+they configure AWS credentials to be able to upload files to S3. You can ask in
+the #internal-airflow-ci-cd channel on Airflow Slack to get your AWS credentials configured.
+
+You can checkout locally a version of airflow repo that you need and apply any cherry-picks you need before
+running publishing.
+
+This is done using breeze. You also need to have aws CLI installed and configured credentials to be able
+to upload files to S3. You can get credentials from one of the admins of Airflow's AWS account. The
+region to set for AWS is `us-east-2`.
+
+Note that it is advise to add `--dry-run` if you just want to see what would happen. Also you can use
+the `s3://staging-docs-airflow-apache-org/docs/` bucket to test the publishing using staging site.
+
+```bash
+breeze build-docs "<package_id1>" "<package_id2>" --docs-only
+mkdir /tmp/airflow-site
+breeze release-management publish-docs --override-versioned --airflow-site-directory /tmp/airflow-site
+breeze release-management publish-docs-to-s3 --source-dir-path /tmp/airflow-site/docs-archive \
+ --destination-location s3://live-docs-airflow-apache-org/docs/ --stable-versions \
+ --exclude-docs "<package_id1_to_exclude> <package_id2_to_exclude>" [--dry-run]
+```
+
+## Manually publishing documentation via `apache-airflow-site-archive` repo
+
+If you do not have S3 credentials and want to be careful about publishing the documentation you can also
+use publishing via `apache-airflow-site-archive` repository. This is a little more complex, but it allows
+you to publish documentation without having S3 credentials.
+
+The process is as follows:
+
+1. Run `Sync s3 to GitHub` workflow in `apache-airflow-site-archive` repository. This will download the
+   latest version of the documentation from S3 to `airflow-site-archive` repository (this should be normally
+   not needed, if automated synchronization works).
+2. Checkout `apache-airflow-site-archive` repository and create a branch for your changes.
+3. Build documentation locally in `apache-airflow` repo with any cherry-picks and modifications you need and
+   publish the docs to the checked out `airflow-site-archive` branch
+
+```bash
+breeze build-docs "<package_id1>" "<package_id2>" --docs-only
+breeze release-management publish-docs --override-versioned --airflow-site-directory <PATH_TO_THE_ARCHIVE_REPO>
+```
+
+4. Commit the changes to `apache-airflow-site-archive` repository and push them to `some` branch of the
+   repository.
+5. Run `Sync GitHub to S3` workflow in `apache-airflow-site-archive` repository. This will upload the modified
+   documentation to S3 bucket. You can choose, whether to sync the changes to `live` or `staging` bucket.
+   The default is `live`. You can also specify which folders to sync - by default all modified folders are synced.
+6. After you synchronize the changes to S3, the Sync `S3 to GitHub` workflow will be triggered
+   automatically and the changes will be synchronized to `airflow-site-archive` `main` branch - so there
+   is no need to merge your changes to `main` branch of `airflow-site-archive` repository. You can safely
+   delete the branch you created in step 2.
diff --git a/docs/images/documentation_architecture.md5sum b/docs/images/documentation_architecture.md5sum
new file mode 100644
index 0000000000000..394ee887a84e3
--- /dev/null
+++ b/docs/images/documentation_architecture.md5sum
@@ -0,0 +1 @@
+1f460a38c43a136d03d3891ea7299d09
diff --git a/docs/images/documentation_architecture.png b/docs/images/documentation_architecture.png
new file mode 100644
index 0000000000000..20bf207fd40d7
Binary files /dev/null and b/docs/images/documentation_architecture.png differ
diff --git a/docs/images/documentation_architecture.py b/docs/images/documentation_architecture.py
new file mode 100644
index 0000000000000..fff1d3b911789
--- /dev/null
+++ b/docs/images/documentation_architecture.py
@@ -0,0 +1,121 @@
+# 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.
+from __future__ import annotations
+
+from pathlib import Path
+
+from diagrams import Cluster, Diagram, Edge
+from diagrams.aws.storage import S3
+from diagrams.custom import Custom
+from diagrams.onprem.client import User, Users
+from diagrams.onprem.network import Apache
+from rich.console import Console
+
+MY_DIR = Path(__file__).parent
+MY_FILENAME = Path(__file__).with_suffix("").name
+
+
+console = Console(width=400, color_system="standard")
+
+GITHUB_LOGO = MY_DIR / "logos" / "github.png"
+
+graph_attr = {
+    "concentrate": "false",
+    "splines": "splines",
+}
+
+edge_attr = {
+    "minlen": "1",
+}
+
+
+def generate_documentation_architecture_diagram():
+    image_file = (MY_DIR / MY_FILENAME).with_suffix(".png")
+
+    console.print(f"[bright_blue]Generating architecture image {image_file}")
+    with Diagram(
+        name="",
+        show=False,
+        direction="LR",
+        filename=MY_FILENAME,
+        edge_attr=edge_attr,
+        graph_attr=graph_attr,
+    ):
+        release_manager = User("Release Manager\n")
+        committer = User("Committer")
+
+        with Cluster("Airflow GitHub repos", graph_attr={"margin": "30"}):
+            apache_airflow_repo = Custom("apache-airflow", GITHUB_LOGO.as_posix())
+            apache_airflow_site_repo = Custom("apache-airflow-site", GITHUB_LOGO.as_posix())
+
+            (
+                apache_airflow_site_repo
+                >> Edge(color="black", style="solid", label="Publish site (manual)\nMerge PR")
+                >> committer
+            )
+            (
+                apache_airflow_site_repo
+                >> Edge(color="blue", style="solid", label="\n\n\nPull Theme (auto)")
+                >> release_manager
+            )
+            (
+                apache_airflow_repo
+                >> Edge(
+                    color="black",
+                    style="solid",
+                    label="Publish package docs (manual)\nPublish Docs to S3 Workflow",
+                )
+                >> release_manager
+            )
+
+        with Cluster("Live Docs", graph_attr={"margin": "80"}):
+            live_bucket = S3("live-docs-airflow-apache-org")
+            apache_airflow_site_archive_repo = Custom("apache-airflow-site-archive", GITHUB_LOGO.as_posix())
+            apache_live_webserver = Apache("https://airflow.apache.org")
+
+            release_manager >> Edge(color="black", style="solid", label="Publish package docs") >> live_bucket
+            (
+                committer
+                >> Edge(color="black", style="solid", label="Publish site\n\nInclude .htaccess proxy")
+                >> apache_live_webserver
+            )
+
+            (
+                live_bucket
+                >> Edge(color="black", style="solid", label="Proxy docs from S3", minlen="2")
+                >> apache_live_webserver
+            )
+            (
+                live_bucket
+                >> Edge(color="black", style="dashed", label="Archive docs (auto)", minlen="2")
+                >> apache_airflow_site_archive_repo
+            )
+
+            (
+                apache_airflow_site_archive_repo
+                >> Edge(color="red", style="dotted", label="Fix docs (manual)", reverse=False, forward=False)
+                >> live_bucket
+            )
+
+        users = Users("Users")
+        apache_live_webserver >> Edge(color="black", style="solid", label="Served via Fastly") >> users
+
+    console.print(f"[green]Generated architecture image {image_file}")
+
+
+if __name__ == "__main__":
+    generate_documentation_architecture_diagram()
diff --git a/docs/images/logos/github.png b/docs/images/logos/github.png
new file mode 100644
index 0000000000000..28629731ec86b
Binary files /dev/null and b/docs/images/logos/github.png differ
diff --git a/docs/images/publish-site.png b/docs/images/publish-site.png
new file mode 100644
index 0000000000000..f82d99df365ad
Binary files /dev/null and b/docs/images/publish-site.png differ
diff --git a/docs/images/publish_airflow.png b/docs/images/publish_airflow.png
new file mode 100644
index 0000000000000..78c01fffe5177
Binary files /dev/null and b/docs/images/publish_airflow.png differ
diff --git a/docs/images/sync_github_to_s3.png b/docs/images/sync_github_to_s3.png
new file mode 100644
index 0000000000000..8d6a02430dd12
Binary files /dev/null and b/docs/images/sync_github_to_s3.png differ
