From f0e02f5df2bc3ae779ac8c18578deebdfecc7e97 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Thu, 24 Jun 2021 18:00:56 +0100
Subject: [PATCH] Create an index.html file when generating a docs build
 (#10242)

Currently when a new build of the docs is created, an `index.html` file does not exist. Typically this would be generated from a`docs/README.md` file - which we have - however we're currently using [docs/README.md](https://github.com/matrix-org/synapse/blob/394673055db4df49bfd58c2f6118834a6d928563/docs/README.md) to explain the docs and point to the website. It is not part of the content of the website. So we end up not having an `index.html` file, which will result in a 404 page if one tries to navigate to `https://matrix-org.github.io/synapse/<docs_version>/index.html`.

This isn't a really problem for the default version of the documentation (currently `develop`), as [navigating to the top-level root](https://matrix-org.github.io/synapse/) of the website (without specifying a version) will [redirect](https://github.com/matrix-org/synapse/blob/a77e6925f26597958eccf0ef9956cb13c536e57e/index.html#L2) you to the Welcome and Overview page of the `develop` docs version.

However, ideally once we add a GUI for switching between versions, we'll want to send the user to `matrix-org.github.io/synapse/<version>/index.html`, which currently isn't generated.

This PR modifies the CI that builds the docs to simply copy the rendered [Welcome & Overview page](https://matrix-org.github.io/synapse/develop/welcome_and_overview.html) to `index.html`.
---
 .github/workflows/docs.yaml | 7 ++++++-
 changelog.d/10242.doc       | 1 +
 2 files changed, 7 insertions(+), 1 deletion(-)
 create mode 100644 changelog.d/10242.doc

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index 23b8d7f909..c239130c57 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -23,7 +23,12 @@ jobs:
           mdbook-version: '0.4.9'
 
       - name: Build the documentation
-        run: mdbook build
+        # mdbook will only create an index.html if we're including docs/README.md in SUMMARY.md.
+        # However, we're using docs/README.md for other purposes and need to pick a new page
+        # as the default. Let's opt for the welcome page instead.
+        run: |
+          mdbook build
+          cp book/welcome_and_overview.html book/index.html
 
       # Deploy to the latest documentation directories
       - name: Deploy latest documentation
diff --git a/changelog.d/10242.doc b/changelog.d/10242.doc
new file mode 100644
index 0000000000..2241b28547
--- /dev/null
+++ b/changelog.d/10242.doc
@@ -0,0 +1 @@
+Choose Welcome & Overview as the default page for synapse documentation website.