Merge branch 'main' into DOCSS-1854-html-proofer

Author: rosieyohannan

.circleci/config.yml

@@ -6,7 +6,8 @@ parameters:
     default: ""
 
 orbs:
-  aws-cli: circleci/[email protected]
+  aws-cli: circleci/[email protected]
+  vale: circleci/[email protected]
 
 executors:
   node_executor:
@@ -63,9 +64,9 @@ jobs:
     steps:
       - checkout
       - run:
-          name: Fetch branches matching server-*
+          name: Fetch branches matching server-4*
           command: |
-            for branch in $(git ls-remote --heads origin | awk '{print $2}' | grep 'refs/heads/server-' | sed 's|refs/heads/||'); do
+            for branch in $(git ls-remote --heads origin | awk '{print $2}' | grep 'refs/heads/server-4' | sed 's|refs/heads/||'); do
               echo "[INFO] Fetching branch: $branch"
               git checkout "$branch"
               git pull origin "$branch"
@@ -108,7 +109,6 @@ jobs:
       - notify_error:
           message: "Build job failed for branch ${CIRCLE_BRANCH}"
 
-
   validate:
     executor: ruby_executor
     steps:
@@ -138,7 +138,6 @@ jobs:
       - notify_error:
           message: "Validation job failed for branch ${CIRCLE_BRANCH}"
 
-
   deploy-preview:
     executor: node_executor
     steps:
@@ -192,20 +191,42 @@ jobs:
             fi
       - notify_error:
           message: "Deploy preview job failed for branch ${CIRCLE_BRANCH}"
-
+      # - aws-setup
+      # - run:
+      #     name: Test S3 deployment
+      #     command: |
+      #       set -e
+      #       echo "[INFO] Testing deploy to S3 bucket..."
+      #       aws s3 sync build "s3://circleci-docs-platform-assets/docs/dorian/"
 
   deploy-production:
     executor: node_executor
+    parameters:
+      bucket_dir:
+        default: "dorian"
+        description: The directory in the bucket to deploy to.
+        type: string
+      bucket_name:
+        description: The name of the s3 bucket where static assets are stored.
+        type: string
+      build_dir:
+        default: "build"
+        description: The path to the docs build directory
+        type: string
     steps:
       - attach_workspace:
           at: .
       - aws-setup
       - run:
           name: Deploy Production Site to S3
           command: |
+            AWS_S3_BUCKET=<< parameters.bucket_name >>
+            BUCKET_DIRECTORY=<< parameters.bucket_dir >>
+            BUILD_DIRECTORY=<< parameters.build_dir >>
+
             set -e
             echo "[INFO] Deploying production site..."
-            aws s3 sync build s3://${DOCS_BUILD_BUCKET}/ --delete --endpoint-url ${S3_ENDPOINT}
+            aws s3 sync "$BUILD_DIRECTORY" "s3://$AWS_S3_BUCKET/$BUCKET_DIRECTORY/"
       - notify_error:
           message: "Production deployment job failed for branch ${CIRCLE_BRANCH}"
 
@@ -250,8 +271,14 @@ jobs:
               echo "[WARN] Tag '${TAG}' not found."
             fi
 
-
 workflows:
+  lint:
+    unless:
+      equal: [main, << pipeline.git.branch >>]
+    jobs:
+      - vale/lint:
+          reference_branch: main
+          base_dir: docs
   build_validate_and_deploy:
     when:
       equal: ["", << pipeline.parameters.cleanup_preview_branch >>]
@@ -265,13 +292,28 @@ workflows:
           filters:
             branches:
               ignore: main
-          context: circleci-docs-static
+          context:
+            [
+              circleci-docs-static,
+              docs-platform-assets,
+              web-ui-npm,
+              web-ui-datadog,
+            ]
       - deploy-production:
           requires: [validate]
           filters:
             branches:
               only: main
-          context: circleci-docs-static
+          context:
+            [
+              circleci-docs-static,
+              docs-platform-assets,
+              web-ui-npm,
+              web-ui-datadog,
+            ]
+          bucket_dir: "dorian"
+          bucket_name: "circleci-docs-platform-assets/docs"
+          build_dir: "build"
   cleanup_preview:
     when: pipeline.parameters.cleanup_preview_branch != ""
     jobs:

.gitignore

@@ -7,4 +7,5 @@ ui/node_modules/
 ui/public/
 ui/**/.DS_Store
 extensions/.temp
-.env
+.env
+.vscode/

.vale.ini

@@ -0,0 +1,21 @@
+StylesPath = styles
+
+Vocab = Docs
+
+MinAlertLevel = suggestion
+
+Packages = Readability
+
+[asciidoctor]
+# attribute = value
+#
+# where 'YES' enables and 'NO' disables.
+
+# enable
+experimental = YES
+
+# assign a specific value
+attribute-missing = drop
+
+[*.adoc]
+BasedOnStyles = circleci-docs, Vale, Readability, Openly

DEVELOPMENT.md

@@ -84,12 +84,12 @@ The site will be available at `http://localhost:3000` by default.
   npm run build:docs
   ```
 
-- **Fetch server branches** (for server admin docs). You will need to have local copies of all server-* branches to be able to build the full docs site locally:
+- **Fetch server branches** (for server admin docs). You will need to have local copies of all server-4* branches to be able to build the full docs site locally:
   ```bash
   npm run fetch-server-branches
   ```
 
-- **Force fetch server branches** if you want to force all your server-* branches to the state of the upstream "current" versions, use the --force flag. This is recommended if you have no local changes on any server-* branch:
+- **Force fetch server branches** if you want to force all your server-4* branches to the state of the upstream "current" versions, use the --force flag. This is recommended if you have no local changes on any server-4* branch:
 
   ```bash
   npm run fetch-server-branches --force
@@ -257,7 +257,7 @@ When changes are made to the main branch to the build processes, the UI, or all
 3. Run `git rebase main`
 4. Push those changes with `git push --force-with-lease origin server-4.1` - remember to use the correct server branch number.
 
-This should be done for every server-* branch.
+This should be done for every server-4* branch.
 
 ### Creating a New Component
 

README.md

@@ -41,7 +41,7 @@ This technical documentation consists of several specialized files:
    cd circleci-docs-static
    npm ci
    ```
-2. **Make sure you've cloned server-* branches (Server Administration Docs)**
+2. **Make sure you've cloned server-4* branches (Server Administration Docs)**
 
 ```bash
    npm run fetch-server-branches

antora-playbook.yml

@@ -16,7 +16,7 @@ content:
     start_path: docs/orbs
   - url: .
     start_path: docs/server-admin
-    branches: [server-*]
+    branches: [server-4*]
   - url: .
     start_path: docs/contributors
 ui:

custom-template.hbs

@@ -0,0 +1,85 @@
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf8" />
+  <title>{{title}}</title>
+  <!-- needed for adaptive design -->
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body {
+      padding: 0;
+      margin: 0;
+    }
+
+    /* Custom logo styling - properly centered and clickable */
+    .custom-logo {
+      position: fixed;
+      top: 15px;
+      left: 15px;
+      z-index: 1001;
+      padding: 12px; /* Equal padding on all sides */
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      width: fit-content;
+      transition: all 0.2s ease;
+    }
+
+    .custom-logo a:hover {
+      transform: translateY(-1px);
+    }
+
+    .custom-logo img {
+      height: 32px;
+      width: auto;
+      display: block;
+    }
+
+    /* Adjust sidebar to avoid logo overlap */
+    .menu-content {
+      padding-top: 70px !important;
+    }
+
+    /* Hide logo on very small screens to avoid clutter */
+    @media (max-width: 480px) {
+      .custom-logo {
+        display: none;
+      }
+    }
+
+    /* Adjust for medium screens */
+    @media (max-width: 768px) {
+      .custom-logo {
+        position: relative;
+        top: 0;
+        left: 0;
+        margin: 15px auto;
+        display: block;
+        text-align: center;
+        max-width: none;
+        width: fit-content;
+        padding: 15px 20px;
+      }
+
+      .menu-content {
+        padding-top: 20px !important;
+      }
+    }
+  </style>
+  {{{redocHead}}}
+  {{#unless disableGoogleFont}}<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">{{/unless}}
+</head>
+
+<body>
+  <!-- Clickable logo that routes to docs homepage -->
+  <div class="custom-logo">
+    <a href="../../reference/api-homepage.html" title="Back to CircleCI Documentation">
+      <img src="logo.svg" alt="CircleCI" />
+    </a>
+  </div>
+
+  {{{redocHTML}}}
+</body>
+
+</html>

docs/guides/modules/about-circleci/pages/about-circleci.adoc

@@ -15,7 +15,7 @@ image::guides:ROOT:circleci-system-diagram.png[CircleCI process diagram]
 [#what-is-ci-cd]
 == What is CI/CD?
 
-*Continuous integration (CI)* is a practice that integrates code into a chosen branch of a shared repository, early and often. Instead of building out features in isolation and integrating them at the end of a development cycle, code is integrated with the shared repository by developers multiple times throughout the day by committing daily to a shared mainline. Every commit triggers automated tests and builds. If these fail, they can be repaired quickly.
+*Continuous integration (CI)* is a practice that integrates code into a chosen branch of a shared repository, early and often. Instead of building out features in isolation and integrating them at the end of a development cycle, code is integrated with the shared repository multiple times throughout the day. Every commit to a shared mainline triggers automated tests and builds. If these fail, they can be repaired quickly.
 
 *Continuous delivery (CD)* is a practice that produces reliable releases to a chosen development environment, like a staging or production branch.
 

gulp.d/tasks/build-api-docs.js

@@ -183,19 +183,50 @@ function buildApiV2(callback) {
             // STEP 6: Build final HTML documentation
             // Redocly transforms the OpenAPI spec into beautiful, interactive docs
             console.log('🏗️  Building docs with Redocly CLI...')
-            exec('npx @redocly/cli build-docs build/temp-api-v2/openapi-final.json --output build/api/v2/index.html', (err, stdout, stderr) => {
+
+            // Build options for enhanced customization (all free options):
+            // --title: Custom page title
+            // --theme.openapi.disableSearch: Disable search (if needed)
+            // --theme.openapi.hideDownloadButton: Hide download button
+            // --template: Custom template (requires template file)
+            // --options.maxDisplayedEnumValues: Limit enum display
+
+            const buildCommand = [
+              'npx @redocly/cli build-docs build/temp-api-v2/openapi-final.json',
+              '--output build/api/v2/index.html',
+              '--config redocly.yaml',
+              '--template custom-template.hbs',
+              '--title "CircleCI API v2 Documentation"',
+              '--disableGoogleFont=false',
+              // Additional options for free version:
+              // '--theme.openapi.hideDownloadButton=true',
+              // '--theme.openapi.disableSearch=true',
+              // '--theme.openapi.nativeScrollbars=true'
+            ].join(' ')
+
+            exec(buildCommand, (err, stdout, stderr) => {
               if (err) {
                 console.error('❌ Failed to build API docs:', err)
                 return callback(err)
               }
 
               console.log('✅ API v2 docs built successfully')
 
-              // STEP 7: Cleanup temporary files
-              // Remove intermediate files to keep build directory clean
-              exec('rm -rf build/temp-api-v2', () => {
-                console.log('🎉 API v2 documentation build completed!')
-                callback()
+              // STEP 7: Copy logo file for template
+              console.log('📋 Copying logo file...')
+              exec('cp logo.svg build/api/v2/', (err) => {
+                if (err) {
+                  console.warn('⚠️  Warning: Could not copy logo file:', err.message)
+                } else {
+                  console.log('✅ Logo file copied successfully')
+                }
+
+                // STEP 8: Cleanup temporary files
+                // Remove intermediate files to keep build directory clean
+                exec('rm -rf build/temp-api-v2', () => {
+                  console.log('🎉 API v2 documentation build completed!')
+                  callback()
+                })
               })
             })
           })