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/*"] } } }