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](394673055d/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](a77e6925f2/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`.
This commit is contained in:
Andrew Morgan 2021-06-24 18:00:56 +01:00 committed by GitHub
parent 8165ba48b1
commit f0e02f5df2
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 7 additions and 1 deletions

View file

@ -23,7 +23,12 @@ jobs:
mdbook-version: '0.4.9' mdbook-version: '0.4.9'
- name: Build the documentation - 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 # Deploy to the latest documentation directories
- name: Deploy latest documentation - name: Deploy latest documentation

1
changelog.d/10242.doc Normal file
View file

@ -0,0 +1 @@
Choose Welcome & Overview as the default page for synapse documentation website.