C2-2734: Fix 404s on stargate.io/docs homepage (#265)

* add nojekyll * update links from http to https * resolve index.html issue * change API links to xrefs * remove unnecessary line from gitignore * document purpose of redirect_facility * revert nojekyll changes * Remove index.html workaround * align other playbooks
stargate · Jul 25, 2023 · 293e214 · 293e214
1 parent 0e1b5f4
commit 293e214
Show file tree

Hide file tree

Showing 14 changed files with 61 additions and 47 deletions.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -33,22 +33,18 @@ jobs:
             if [  -f "$FILE" ]; then
             rm antora.yml;
             echo "antora.yml removed"
-          fi          
+          fi
           ln -s antora-stargate.yml antora.yml
       - name: Setup gradle
         uses: gradle/gradle-build-action@v2
       - name: Execute gradle build to run antora
-        run: ./gradlew antora   
+        run: ./gradlew antora
       - name: "Fix attachments"
         run: |
           sudo mv $GITHUB_WORKSPACE/build/$SITE_DIR/$SUB_DIR/develop/_attachments $GITHUB_WORKSPACE/build/$SITE_DIR/$SUB_DIR/develop/attachments
           sudo sed -i 's/_attachments/attachments/g' $GITHUB_WORKSPACE/build/$SITE_DIR/$SUB_DIR/develop/api.html
           ls -ltra $GITHUB_WORKSPACE/build/$SITE_DIR
-          grep attachment $GITHUB_WORKSPACE/build/$SITE_DIR/$SUB_DIR/develop/api.html    
-      - name: "Copy index.html required for website"
-        run: |
-          sudo mv $GITHUB_WORKSPACE/index.html $GITHUB_WORKSPACE/build/$SITE_DIR
-          ls -ltra $GITHUB_WORKSPACE/build/$SITE_DIR
+          grep attachment $GITHUB_WORKSPACE/build/$SITE_DIR/$SUB_DIR/develop/api.html
       - name: "Upload generated site"
         uses: actions/upload-artifact@v3
         with:
@@ -71,7 +67,7 @@ jobs:
        with:
          name: site
          path: "${{ github.workspace }}/${{ env.SITE_DIR }}"
-         
+
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:

diff --git a/.gitignore b/.gitignore
@@ -2,7 +2,6 @@ build
 .DS_store
 *~
 package-lock.json
-docs-src/.DS_Store
 
 # Logs
 logs

diff --git a/docs-src/stargate-core/antora-stargate.yml b/docs-src/stargate-core/antora-stargate.yml
@@ -1,6 +1,7 @@
 name: latest
 title: Stargate Documentation
 version: ~
+start_page: index.adoc
 nav:
 - modules/ROOT/cnav.adoc
 - modules/quickstart/nav.adoc

diff --git a/docs-src/stargate-core/modules/ROOT/cnav.adoc b/docs-src/stargate-core/modules/ROOT/cnav.adoc
@@ -1,4 +1,4 @@
-* xref:core-index.adoc[Stargate Overview]
+* xref:index.adoc[Stargate Overview]
 // * xref:release-notes.adoc[Release notes]
 * xref:FAQ.adoc[FAQ]
 
diff --git a/...e-core/modules/ROOT/pages/core-index.adoc → ...argate-core/modules/ROOT/pages/index.adoc b/...e-core/modules/ROOT/pages/core-index.adoc → ...argate-core/modules/ROOT/pages/index.adoc
@@ -1,4 +1,5 @@
 = The Stargate API Documentation
+:page-aliases: core-index.adoc
 
 * xref:concepts:concepts.adoc[Stargate concepts]
 //* xref:quickstart:quickstart-overview.adoc[Stargate QuickStarts]

diff --git a/docs-src/stargate-develop/modules/develop/pages/api.adoc b/docs-src/stargate-develop/modules/develop/pages/api.adoc
@@ -4,15 +4,15 @@ Stargate provides multiple APIs to interact with your databases.
 
 == Stargate APIs
 
-* http://stargate.io/docs/latest/develop/attachments/docv2.html[{database} Document API v2, window="_blank"]: The Stargate Document API allows you to use schemaless storage of free-form JSON Documents in your {astra_db} database. Get examples of using the Document API in the xref:develop:dev-with-doc.adoc[Developing with the Document API] section.
+* https://stargate.io/docs/latest/develop/attachments/docv2.html[{database} Document API v2, window="_blank"]: The Stargate Document API allows you to use schemaless storage of free-form JSON Documents in your {astra_db} database. Get examples of using the Document API in the xref:develop:dev-with-doc.adoc[Developing with the Document API] section.
 
-* http://stargate.io/docs/latest/develop/attachments/restv2.html[{database} REST API v2, window="_blank"]: The Stargate REST API allows you to perform standard CRUD operations on your {astra_db} data using a simple, cross-language interface. Get examples of using the REST API v2 in the xref:develop:dev-with-rest.adoc[Developing with the REST API] section.
+* https://stargate.io/docs/latest/develop/attachments/restv2.html[{database} REST API v2, window="_blank"]: The Stargate REST API allows you to perform standard CRUD operations on your {astra_db} data using a simple, cross-language interface. Get examples of using the REST API v2 in the xref:develop:dev-with-rest.adoc[Developing with the REST API] section.
 
 * xref:graphql.adoc[Stargate GraphQL API, window="_blank"]: The GraphQL playground allows you to easily interact with your data using GraphQL types, queries, and mutations. For every table in your keyspace, a series of GraphQL objects are generated, along with queries and mutations that allow you to search and modify the table data. Get examples of using the GraphQL API in the xref:develop:graphql.adoc[Developing with the GraphQL API] section.
 
 * xref:dev-with-grpc.adoc[Stargate gRPC API, window="_blank"]: link:https://grpc.io/docs/what-is-grpc/introduction[gRPC^] is a modern, open source remote procedure call (RPC) framework. It enables client and server applications to communicate transparently, and makes it easier to build connected systems. Get examples of using the gRPC API in the xref:develop:dev-with-grpc.adoc[Developing with the gRPC API] section.
 
 === Prior Stargate version
 
-* http://stargate.io/docs/latest/develop/attachments/restv1.html[Stargate REST API v1, window="_blank"]
+* https://stargate.io/docs/latest/develop/attachments/restv1.html[Stargate REST API v1, window="_blank"]
 
diff --git a/docs-src/stargate-develop/modules/develop/pages/dev-with-doc.adoc b/docs-src/stargate-develop/modules/develop/pages/dev-with-doc.adoc
@@ -8,9 +8,9 @@ Because the Document API uses schemaless data, no data modeling is required!
 
 If the Document API is used with Apache Cassandra, document indexing is accomplished with https://cassandra.apache.org/doc/trunk/cassandra/cql/indexes.html[Cassandra secondary indexes].
 
-// LLP 07.25.2022 Add a link to SAI when it is added and published in the CQL doc. 
+// LLP 07.25.2022 Add a link to SAI when it is added and published in the CQL doc.
 
-If the Document API is used with DataStax Enterprise, SAI indexing is used. 
+If the Document API is used with DataStax Enterprise, SAI indexing is used.
 The blog https://stargate.io/2020/10/19/the-stargate-cassandra-documents-api.html[The Stargate Cassandra Documents API] describes the underlying structure used to store collections.
 
 == Information about namespaces and collections
@@ -32,10 +32,10 @@ include::develop:partial$prereqs-stargate.adoc[]
 == API reference
 
 If you prefer to learn using a QuickStart, try out the xref:quickstart:qs-document.adoc[Stargate Document QuickStart, window="_blank"].
-To view the API Reference, see xref:develop:attachment$docv2.html[{database} Document API, window="_blank"].
+To view the API Reference, see https://stargate.io/docs/latest/develop/attachments/docv2.html[{database} Document API, window="_blank"].
 
-// You may wish to run the following examples in https://postman.com[Postman]. 
-// The button below allows you to fork a copy of the collection and environment that will allow you to execute all the commands shown, if 
+// You may wish to run the following examples in https://postman.com[Postman].
+// The button below allows you to fork a copy of the collection and environment that will allow you to execute all the commands shown, if
 // you have a local Stargate instance running in Docker.
 
 // image::https://run.pstmn.io/button.svg[link={docapi-postman}, window="_blank"]

diff --git a/docs-src/stargate-develop/modules/develop/pages/dev-with-rest.adoc b/docs-src/stargate-develop/modules/develop/pages/dev-with-rest.adoc
@@ -14,7 +14,7 @@ include::develop:partial$prereqs-stargate.adoc[]
 == API reference
 
 If you prefer to learn using a QuickStart, try out the xref:quickstart:qs-rest.adoc[Stargate REST QuickStart, window="_blank"].
-To view the API Reference, see xref:develop:attachment$restv2.html[{database} REST API, window="_blank"].
+To view the API Reference, see https://stargate.io/docs/latest/develop/attachments/restv2.html[{database} REST API, window="_blank"].
 
 // STARGATE ONLY
 ifeval::["{product}" == "Stargate"]

diff --git a/docs-src/stargate-develop/modules/quickstart/pages/qs-document.adoc b/docs-src/stargate-develop/modules/quickstart/pages/qs-document.adoc
@@ -56,5 +56,5 @@ include::develop:page$api-doc/doc-document-deleting.adoc[Deleting documents and
 
 Voila! For more information on the Document API, see the
 xref:develop:dev-with-doc.adoc[Using the Document API]
-or the https://stargate.io/docs/latest/develop/attachments/docv2.html[Document API] in the
+or the https://stargate.io/docs/latest/develop/attachments/docv2.html[Document API, window="_blank"] in the
 API references section.
diff --git a/docs-src/stargate-develop/modules/quickstart/pages/qs-rest.adoc b/docs-src/stargate-develop/modules/quickstart/pages/qs-rest.adoc
@@ -50,5 +50,5 @@ include::develop:page$api-rest/rest-deleting-rows.adoc[Deleting rows in your tab
 
 Voila! For more information on the REST API, see the see the
 xref:develop:dev-with-rest.adoc[Using the REST API]
-or the https://stargate.io/docs/latest/develop/attachments/restv2.html[REST API] in the
+or the https://stargate.io/docs/latest/develop/attachments/restv2.html[REST API, window="_blank"] in the
 API references section.
diff --git a/index.html b/index.html
diff --git a/playbooks/site-local-stargate.yaml b/playbooks/site-local-stargate.yaml
@@ -5,9 +5,10 @@ antora:
   - '@antora/collector-extension'
 site:
   title: Stargate documentation
-  start_page: stargate-core::core-index.adoc
+  url: https://stargate.io/docs
+  start_page: latest::index.adoc
 
-output: 
+output:
   dir: ./../build/stargate
 
 content:
@@ -27,6 +28,14 @@ ui:
   # override the default _ dir for assets, as Jekyll will delete them
   output_dir: assets
 
+urls:
+  # `static` is already Antora's default value for `redirect_facility`. However,
+  # including it here is meant to signal to others that it shouldn't be changed.
+  # GitHub Pages doesn't currently accept or provide access to URL redirection
+  # configuration files, therefore setting this to anything other than `static`
+  # will break redirection within the Stargate docs.
+  redirect_facility: static
+
 asciidoc:
   attributes:
     source-highlighter: highlightjs
@@ -76,7 +85,7 @@ asciidoc:
     base_gql_api: '/graphql'
 
     astra_ui: 'Astra Portal'
-    astra_db: 'Astra DB'    
+    astra_db: 'Astra DB'
 
     rkeyspace: 'users_keyspace'
     rkeyspace-dcs: 'users_keyspace-dcs'
@@ -93,7 +102,7 @@ asciidoc:
     collection: 'library'
     collection2: 'library2'
     user1: 'Jane'
-    user2: 'Amy'  
+    user2: 'Amy'
     docid: '2545331a-aaad-45d2-b084-9da3d8f4c311'
     bookdocid: 'native-son-doc-id'
     readerdocid: 'John-Smith'
@@ -107,4 +116,4 @@ asciidoc:
     glossary-url: 'https://docs.datastax.com/en/glossary/docs/'
 
   extensions:
-     - ./lib/tabs-block.js
+  - ./lib/tabs-block.js
diff --git a/playbooks/site-publish-stargate-ghaction.yaml b/playbooks/site-publish-stargate-ghaction.yaml
@@ -4,10 +4,10 @@ antora:
   - '@antora/collector-extension'
 site:
   title: Stargate documentation
-  url: https://stargate.io/
-  start_page: stargate-core::core-index.adoc
-  
-output: 
+  url: https://stargate.io/docs
+  start_page: latest::index.adoc
+
+output:
   dir: ./../build/stargate
 
 content:
@@ -27,6 +27,14 @@ ui:
   # override the default _ dir for assets, as Jekyll will delete them
   output_dir: assets
 
+urls:
+  # `static` is already Antora's default value for `redirect_facility`. However,
+  # including it here is meant to signal to others that it shouldn't be changed.
+  # GitHub Pages doesn't currently accept or provide access to URL redirection
+  # configuration files, therefore setting this to anything other than `static`
+  # will break redirection within the Stargate docs.
+  redirect_facility: static
+
 asciidoc:
   attributes:
     source-highlighter: highlightjs
@@ -75,8 +83,8 @@ asciidoc:
     base_doc_api: '/v2/namespaces'
     base_gql_api: '/graphql'
 
-    astra_ui: 'Astra Portal'  
-    astra_db: 'Astra DB'      
+    astra_ui: 'Astra Portal'
+    astra_db: 'Astra DB'
 
     rkeyspace: 'users_keyspace'
     rkeyspace-dcs: 'users_keyspace-dcs'
@@ -93,7 +101,7 @@ asciidoc:
     collection: 'library'
     collection2: 'library2'
     user1: 'Jane'
-    user2: 'Amy'  
+    user2: 'Amy'
     docid: '2545331a-aaad-45d2-b084-9da3d8f4c311'
     bookdocid: 'native-son-doc-id'
     readerdocid: 'John-Smith'
@@ -107,5 +115,4 @@ asciidoc:
     glossary-url: 'https://docs.datastax.com/en/glossary/docs/'
 
   extensions:
-      - ./lib/tabs-block.js
-
+  - ./lib/tabs-block.js
diff --git a/playbooks/site-publish-stargate.yaml b/playbooks/site-publish-stargate.yaml
@@ -1,8 +1,9 @@
 site:
   title: Stargate documentation
-  start_page: stargate-core::core-index.adoc
+  url: https://stargate.io/docs
+  start_page: latest::index.adoc
 
-output: 
+output:
   dir: ~/work/docs/build/site
 
 content:
@@ -22,6 +23,14 @@ ui:
   # override the default _ dir for assets, as Jekyll will delete them
   output_dir: assets
 
+urls:
+  # `static` is already Antora's default value for `redirect_facility`. However,
+  # including it here is meant to signal to others that it shouldn't be changed.
+  # GitHub Pages doesn't currently accept or provide access to URL redirection
+  # configuration files, therefore setting this to anything other than `static`
+  # will break redirection within the Stargate docs.
+  redirect_facility: static
+
 asciidoc:
   attributes:
     source-highlighter: highlightjs
@@ -88,7 +97,7 @@ asciidoc:
     collection: 'library'
     collection2: 'library2'
     user1: 'Jane'
-    user2: 'Amy'  
+    user2: 'Amy'
     docid: '2545331a-aaad-45d2-b084-9da3d8f4c311'
     bookdocid: 'native-son-doc-id'
     readerdocid: 'John-Smith'
@@ -102,4 +111,4 @@ asciidoc:
     glossary-url: 'https://docs.datastax.com/en/glossary/docs/'
 
   extensions:
-     - ~/work/docs/playbooks/lib/tabs-block.js
+  - ~/work/docs/playbooks/lib/tabs-block.js