From f4242cf31f8e4d9abf9e6b26cfe84cd631dc4c1e Mon Sep 17 00:00:00 2001 From: Brian Zelip Date: Sun, 17 Nov 2024 13:45:58 -0500 Subject: [PATCH] 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 --- astro.config.mjs | 3 +- cypress/e2e/sidebar.cy.js | 13 +++++++ cypress/e2e/sitemap.cy.js | 10 +++-- package.json | 4 +- src/components/overrides/Sidebar.astro | 53 ++++++++++++++++++++++++++ src/content/docs/about/development.md | 10 ++--- src/styles/custom.css | 2 +- src/utils/gitMetadata.mjs | 25 ++++++++++++ tsconfig.json | 4 +- 9 files changed, 111 insertions(+), 13 deletions(-) create mode 100644 cypress/e2e/sidebar.cy.js create mode 100644 src/components/overrides/Sidebar.astro create mode 100644 src/utils/gitMetadata.mjs diff --git a/astro.config.mjs b/astro.config.mjs index bcc5db7..5bb610c 100644 --- a/astro.config.mjs +++ b/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' } }) ] diff --git a/cypress/e2e/sidebar.cy.js b/cypress/e2e/sidebar.cy.js new file mode 100644 index 0000000..30be7ad --- /dev/null +++ b/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') + } + }) +}) diff --git a/cypress/e2e/sitemap.cy.js b/cypress/e2e/sitemap.cy.js index 2f35b89..6ecda8d 100644 --- a/cypress/e2e/sitemap.cy.js +++ b/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('/') diff --git a/package.json b/package.json index 6bf5d5b..940f3ef 100644 --- a/package.json +++ b/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", diff --git a/src/components/overrides/Sidebar.astro b/src/components/overrides/Sidebar.astro new file mode 100644 index 0000000..7c803b3 --- /dev/null +++ b/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 +--- + + + +{ + isDev && ( + + ) +} + + diff --git a/src/content/docs/about/development.md b/src/content/docs/about/development.md index 0e0ee5a..f1ac7a7 100644 --- a/src/content/docs/about/development.md +++ b/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 diff --git a/src/styles/custom.css b/src/styles/custom.css index fa65f30..2fffbfc 100644 --- a/src/styles/custom.css +++ b/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); } } diff --git a/src/utils/gitMetadata.mjs b/src/utils/gitMetadata.mjs new file mode 100644 index 0000000..5662d34 --- /dev/null +++ b/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} 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}`) + } +} diff --git a/tsconfig.json b/tsconfig.json index 2cacac4..e6f4b73 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -3,7 +3,9 @@ "compilerOptions": { "baseUrl": ".", "paths": { - "@*": ["src/*"] + "@components/*": ["src/components/*"], + "@images/*": ["src/images/*"], + "@utils/*": ["src/utils/*"] } } }