DOC-4217: Add “page source” links to preview-src pages (#101) [no-release]

* Add “page source” links to preview-src pages

* Update README with latest automation enhancements

Author: eric-schneider

README.adoc

@@ -18,7 +18,8 @@ ifdef::env-github[]
 endif::[]
 // Project URLs:
 :url-project: https://github.com/riptano/docs-ui
-:url-preview: https://riptano.github.io/docs-ui/main
+:url-ui-preview: https://riptano.github.io/docs-ui/main
+:url-ui-bundle-latest: {url-project}/releases/latest
 // :url-ci-pipelines: {url-project}/pipelines
 // :img-ci-status: {url-project}/badges/master/pipeline.svg
 :url-docs-home: https://github.com/riptano/docs-home
@@ -43,10 +44,10 @@ endif::[]
 :url-source-maps: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
 :url-create-release: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
 
-// image:{img-ci-status}[CI Status (GitLab CI), link={url-ci-pipelines}]
-// ifdef::badges[]
-// image:https://img.shields.io/static/v1?label=release&message={current-release}&color=blue[Latest Release,link={url-project}/releases/download/{current-release}/ui-bundle.zip,format=svg]
-// endif::[]
+ifdef::badges[]
+image:https://img.shields.io/github/v/release/riptano/docs-ui?label=latest%20release&labelColor=%23232324&color=%237724aa["Latest UI bundle release (GitHub)", link={url-ui-bundle-latest}]
+image:https://img.shields.io/badge/Preview-%237724aa["Latest UI preview (GitHub Pages)", link={url-ui-preview}]
+endif::[]
 
 This project is used to develop and distribute the UI template for {url-datastax-docs}.
 It is a fork of the {url-antora-default-ui}[Antora Default UI] that has been customized for our needs.
@@ -55,8 +56,9 @@ The repository itself produces a UI bundle that can be applied when generating a
 The UI bundle contains the HTML templates (layouts, partials, and helpers), CSS, JavaScript, fonts, and (site-wide) images.
 As such, it provides both the visual theme and user interactions for the documentation site.
 
-You can see a preview of the DataStax Docs UI at {url-preview}.
+* Latest UI preview: {url-ui-preview}
 
+* Latest UI bundle release: {url-ui-bundle-latest}
 
 toc::[]
 
@@ -243,6 +245,11 @@ This works by monitoring the project for changes, running the `preview:build` ta
 
 Press kbd:[Ctrl+C] to stop the preview server and end the continuous build.
 
+[NOTE]
+====
+Opening or updating a pull request against the `main` branch triggers an automatic `gulp preview` deployment to GitHub Pages so that reviewers can view your latest changes without having to run the preview locally.
+====
+
 [#create-bundle]
 === Package for use with Antora
 
@@ -267,6 +274,12 @@ gulp bundle:pack
 
 The UI bundle will again be available at [.path]_build/ui-bundle.zip_.
 
+[NOTE]
+====
+UI bundles for the DataStax documentation site are automatically published via automation.
+See <<automatic-ui-release>>.
+====
+
 ==== Source maps
 
 The build consolidates all the CSS and client-side JavaScript into combined files, [.path]_site.css_ and [.path]_site.js_, respectively, in order to reduce the size of the bundle.
@@ -288,67 +301,28 @@ In this case, the bundle will include the source maps, which can be used for deb
 
 ==== Using TailwindCSS
 
-This project uses TailwindCSS. To learn more see xref:{url-tailwind-readme}[TailwindCSS README].
+This project uses TailwindCSS.
+To learn more see xref:{url-tailwind-readme}[TailwindCSS README].
 
-== Release the UI bundle
+[#automatic-ui-release]
+== Automatic UI bundle release
 
 Once you're satisfied with the changes you've made to the UI, you'll need to open a pull request to merge your changes into the `main` branch.
-After your changes have been reviewed and merged, you can then choose to make those changes available in the production UI by publishing a new release to this repository and attaching the latest `ui-bundle.zip` file.
+Upon merging a pull request into `main`, the following automation occurs:
 
-=== Bundle release procedure
+. A new UI bundle is built using `gulp bundle` (linting also occurs during this step).
 
-. Start by making sure you've completed the <<prerequisites>>.
+. Assuming a successful build, a new tag is applied to the latest commit (incremented from the previous `prod-#` tag).
 
-. Create the release commit.
-+
-Edit https://github.com/riptano/docs-ui/blob/bdf6484e46f41cff17238a7ef5aeae5368622d2c/README.adoc?plain=1#L3[README.adoc] directly in GitHub and increment the `:current-release:` attribute to the next version number.
-+
-[source,asciidoc]
-----
-:current-release: prod-* <.>
-----
-<.>  Add +1 to the version number
-+
-This should be the only change in the commit, and the commit message should take the form of *Release prod-*.
-If you have Admin privileges to the repository, you can commit the changes directly to `main`.
-Otherwise, you'll need to open a PR.
+. A new `prod-#` {url-project}/releases[release] is published with auto-generated release notes and the UI bundle release asset.
 
-. Once the release commit is merged, open your local copy of the repository in a terminal and retrieve the latest changes from `main`.
-+
-[source,shell]
-----
-git switch main && git pull
-----
-
-. Pack the UI bundle as described in <<create-bundle>>.
-+
-[source,shell]
-----
-gulp bundle
-----
-
-. Create a new release (see {url-create-release}[GitHub documentation]).
-.. Create a new tag named after the new version (e.g., `prod-2`).
-The tag needs to target the `main` branch.
-.. Make sure the *Title* of the release is the same name as the tag.
-(The release title and the tag name should always be made the same, as it makes releases easier to identify.)
-.. Instead of manually adding a description for the release, just click *Generate release notes*.
-This automatically adds a description that highlights the functional changes that have been added since the last release.
-.. Attach the UI bundle (`ui-bundle.zip`) as a release asset.
-.. (Optional) Check the box labeled *This is a pre-release* if you don't want the release to be generally available.
-+
-Selecting this option is helpful if you want to publish a new UI bundle for testing purposes.
-You can edit the release later to remove the *Pre-release* label if desired.
-.. When you're ready, publish the release.
-
-Once the new release is published, the attached bundle can then be downloaded from the repository using a unique URL found on the {url-project}/releases[releases page].
-
-[IMPORTANT]
+[TIP]
 ====
-All production builds of the DataStax docs are configured to pull the latest, _non-pre-release_ UI bundle.
-Once you've publish a new release, all subsequent site builds that use the configuration described in <<use-the-ui>> will consume the new UI bundle.
+If you don't want your pull request to trigger an automatic release, e.g. you're only making updates to the README or `preview-src` files, you can skip the automation by including `[no-release]` in the commit message.
 ====
 
+Once the release is published, you can apply it by updating your Antora playbook to point to the new UI bundle URL.
+To apply it to the DataStax documentation site, you'll need to update the playbook in the {url-datastax-docs-repo}[datastax-docs-site] repository.
 
 == Copyright and license
 

preview-src/asciidoc/admonitions.adoc

@@ -3,6 +3,8 @@
 :idseparator: -
 :table-caption!:
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/admonitions.adoc
+
 == Basic admonitions
 
 .Optional title

preview-src/asciidoc/blocks.adoc

@@ -4,6 +4,8 @@
 :example-caption!:
 :stem:
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/blocks.adoc
+
 == Collapsible blocks
 
 .Basic collapsible block

preview-src/asciidoc/code.adoc

@@ -2,6 +2,8 @@
 :idprefix:
 :idseparator: -
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/code.adoc
+
 == Inline code
 
 Monospace text formatting is typically used to represent text shown in `computer terminals` or `code editors` (often referred to as a codespan).
@@ -93,13 +95,17 @@ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor i
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
 ----
 
-=== Text formatting
+=== Text formatting (variables)
 
-[source,bash,subs="quotes"]
+[source,sql,subs="verbatim,quotes"]
 ----
-cd /Users/*_your-name_*/repos/astra-vector-docs/build/site
+DESCRIBE **KEYSPACE_NAME**.**TABLE_NAME**
 ----
 
+Replace the following:
+
+* *`KEYSPACE_NAME`*: The name of the keyspace that contains the table you want to migrate.
+* *`TABLE_NAME`*: The name of the table that contains the data you want to migrate.
 
 == Callouts
 

preview-src/asciidoc/images.adoc

@@ -3,6 +3,8 @@
 :idseparator: -
 :figure-caption!:
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/images.adoc
+
 == Block images
 
 .Optional title

preview-src/asciidoc/lists.adoc

@@ -3,6 +3,8 @@
 :idseparator: -
 :table-caption!:
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/lists.adoc
+
 == Unordered list
 
 * List item

preview-src/asciidoc/tables.adoc

@@ -3,6 +3,8 @@
 :idseparator: -
 :table-caption!:
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/tables.adoc
+
 == Basic table
 
 .Optional title

preview-src/asciidoc/tabsets.adoc

@@ -9,6 +9,8 @@
 :python-icon: image:../img/python-original.svg[,22]
 :shell-icon: image:../img/shell-original.svg[,20]
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/tabsets.adoc
+
 [NOTE]
 ====
 Tabsets depend on the https://github.com/asciidoctor/asciidoctor-tabs[Asciidoctor Tabs] extension.

preview-src/asciidoc/text-formatting.adoc

@@ -3,6 +3,8 @@
 :idseparator: -
 :experimental:
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/asciidoc/text-formatting.adoc
+
 A paragraph can be defined as one or more lines of consecutive text that are logically grouped together.
 To differentiate between paragraphs, you simply need to insert at least one blank line between them.
 

preview-src/page-templates/full.adoc

@@ -1,6 +1,8 @@
 = {company} Astra
 :page-layout: full
 
+*Page source*: https://github.com/riptano/docs-ui/blob/main/preview-src/page-templates/full.adoc
+
 [.max-w-[650px]]
 DataStax Astra is a cutting-edge cloud-native database platform designed to empower developers.
 Harnessing the strengths of vector databases, serverless computing, and real-time streaming, Astra propels application development into the next generation.