Show git info in sidebar in dev mode and test for it

Pass env vars to Cypress via npm scripts
Update about dev docs
Make import aliases explicit per directory
Update Sidebar nav link hover styles

Author: brianzelip

astro.config.mjs

@@ -26,7 +26,8 @@ export default defineConfig({
       sidebar,
       tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4 },
       components: {
-        Footer: './src/components/overrides/Footer.astro'
+        Footer: './src/components/overrides/Footer.astro',
+        Sidebar: './src/components/overrides/Sidebar.astro'
       }
     })
   ]

cypress/e2e/sidebar.cy.js

@@ -0,0 +1,13 @@
+describe('Sidebar', () => {
+  it('shows git metadata only in development mode', () => {
+    cy.visit('/')
+    if (Cypress.env('MODE') === 'production') {
+      cy.get('#starlight__sidebar > .sidebar-content > footer').should(
+        'not.exist'
+      )
+    }
+    if (Cypress.env('MODE') === 'development') {
+      cy.get('#starlight__sidebar > .sidebar-content > footer')
+    }
+  })
+})

cypress/e2e/sitemap.cy.js

@@ -1,8 +1,10 @@
 describe('Sitemap', () => {
-  it('assets are present', () => {
-    cy.request('/sitemap-index.xml')
-    cy.request('/sitemap-0.xml')
-  })
+  if (Cypress.env('MODE') === 'production') {
+    it('assets are present', () => {
+      cy.request('/sitemap-index.xml')
+      cy.request('/sitemap-0.xml')
+    })
+  }
 
   it('is linked from each page', () => {
     cy.visit('/')

package.json

@@ -14,7 +14,9 @@
     "build": "astro build",
     "preview": "astro preview",
     "astro": "astro",
-    "test": "cypress run",
+    "test:dev": "cypress run --env MODE=development",
+    "test:prod": "cypress run --env MODE=production",
+    "test": "npm run test:prod",
     "prettier:check": "prettier --check .",
     "prettier:fix": "prettier --write .",
     "stylelint:check": "stylelint '**/*.{astro,css}' -f verbose",

src/components/overrides/Sidebar.astro

@@ -0,0 +1,53 @@
+---
+import type { Props } from '@astrojs/starlight/props'
+import Default from '@astrojs/starlight/components/Sidebar.astro'
+import gitMetadata from '@utils/gitMetadata.mjs'
+
+const isDev = import.meta.env.DEV
+---
+
+<Default {...Astro.props}><slot /></Default>
+
+{
+  isDev && (
+    <footer>
+      <p>
+        <svg
+          aria-hidden="true"
+          focusable="false"
+          class="octicon octicon-git-branch"
+          viewBox="0 0 16 16"
+          width="16"
+          height="16"
+          fill="currentColor"
+          style="display:inline-block;user-select:none;vertical-align:text-bottom;overflow:visible"
+        >
+          <path d="M9.5 3.25a2.25 2.25 0 1 1 3 2.122V6A2.5 2.5 0 0 1 10 8.5H6a1 1 0 0 0-1 1v1.128a2.251 2.251 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.5 0v1.836A2.493 2.493 0 0 1 6 7h4a1 1 0 0 0 1-1v-.628A2.25 2.25 0 0 1 9.5 3.25Zm-6 0a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Zm8.25-.75a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5ZM4.25 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z" />
+        </svg>
+        {gitMetadata}
+      </p>
+    </footer>
+  )
+}
+
+<style>
+  footer {
+    margin-top: auto;
+    padding-bottom: 0.5rem;
+    font-size: 0.75rem;
+    color: var(--sl-color-gray-3);
+    text-align: center;
+
+    p {
+      text-wrap-mode: nowrap;
+      overflow-x: scroll;
+    }
+  }
+
+  @media (min-width: 800px) {
+    footer {
+      padding-bottom: 0;
+      text-align: left;
+    }
+  }
+</style>

src/content/docs/about/development.md

@@ -1,5 +1,5 @@
 ---
-title: Development and maintenance
+title: Development
 
 # This is the last page in the sidebar, so point to Home next instead of
 # the Help Center which comes after this page in the sidebar
@@ -8,7 +8,7 @@ next:
   label: Home
 ---
 
-Tech Docs is a [Node.js](https://nodejs.org) application, built with [Astro](https://astro.build/) and its [Starlight](https://starlight.astro.build/) documentation site framework. The source code is hosted on [GitHub](https://github.com/archivesspace/tech-docs). The site is statically built and hosted via [Cloudflare Pages](https://pages.cloudflare.com/). Content is written in [Markdown](./authoring#commonly-used-markdown-syntax). When the source code changes, a new set of static files are generated and published shortly after.
+Tech Docs is a [Node.js](https://nodejs.org) application, built with [Astro](https://astro.build/) and its [Starlight](https://starlight.astro.build/) documentation site framework. The source code is hosted on [GitHub](https://github.com/archivesspace/tech-docs). The site is statically built and (temporarily) hosted via [Cloudflare Pages](https://pages.cloudflare.com/). Content is written in [Markdown](./authoring#commonly-used-markdown-syntax). When the source code changes, a new set of static files are generated and published shortly after.
 
 ## Dependencies
 
@@ -147,17 +147,17 @@ npm test
 
 ### Code style
 
-Nearly all files in the Tech Docs code base get formatted by [Prettier](https://prettier.io/) to ensure consistent readability and syntax. Run Prettier locally to find errors and automatically fix errors where possible:
+Nearly all files in the Tech Docs code base get formatted by [Prettier](https://prettier.io/) to ensure consistent readability and syntax. Run Prettier locally to find format errors and automatically fix them when possible:
 
 ```sh
-# Check formatting of .md, .css, .astro, .js, .yml files, etc.
+# Check formatting of .md, .css, .astro, .js, .yml, etc. files
 npm run prettier:check
 
 # Fix any errors that can be overwritten automatically
 npm run prettier:fix
 ```
 
-All CSS in .css and .astro files are linted by [Stylelint](https://stylelint.io/) to help avoid errors and enforce conventions. Run Stylelint locally to find lint errors and automatically fix errors where possible:
+All CSS in .css and .astro files are linted by [Stylelint](https://stylelint.io/) to help avoid errors and enforce conventions. Run Stylelint locally to find lint errors and automatically fix them when possible:
 
 ```sh
 # Check all CSS

src/styles/custom.css

@@ -66,7 +66,7 @@ body > .page > .header {
 #starlight__sidebar ul.top-level ul > li {
   border-color: transparent;
 
-  &:hover {
+  &:not(:has(> details:first-child)):hover {
     border-inline-start-color: var(--sl-color-gray-4);
   }
 }

src/utils/gitMetadata.mjs

@@ -0,0 +1,25 @@
+import { exec } from 'child_process'
+import { promisify } from 'util'
+
+const execPromise = promisify(exec)
+
+export default await gitMetadata()
+
+/**
+ * @returns {Promise<string>} The current branch and latest commit hash,
+ * eg, `${branch}-${commit}`
+ */
+async function gitMetadata() {
+  try {
+    const { stdout, stderr } = await execPromise(
+      'echo `git rev-parse --abbrev-ref HEAD 2>/dev/null`-`git rev-parse --short HEAD 2>/dev/null`'
+    )
+    if (stderr) {
+      throw new Error(`Stderr: ${stderr}`)
+    }
+
+    return stdout.trim()
+  } catch (error) {
+    throw new Error(`Error: ${error.message}`)
+  }
+}

tsconfig.json

@@ -3,7 +3,9 @@
   "compilerOptions": {
     "baseUrl": ".",
     "paths": {
-      "@*": ["src/*"]
+      "@components/*": ["src/components/*"],
+      "@images/*": ["src/images/*"],
+      "@utils/*": ["src/utils/*"]
     }
   }
 }