Skip to content
Tech Docs

Development

Tech Docs is a Node.js application, built with Astro and its Starlight documentation site framework. The source code is hosted on GitHub. The site is statically built and (temporarily) hosted via Cloudflare Pages. Content is written in Markdown. When the source code changes, a new set of static files are generated and published shortly after.

Dependencies

Tech Docs depends on the following open source software (see .nvmrc and package.json for versions):

  1. Node.js - JavaScript development and build environment
  2. Astro - Static site generator conceptually based on “components” (React, Vue, Svelte, etc.) rather than “templates” (Jekyll, Handlebars, Pug, etc.)
    1. Starlight - Astro plugin and theme for documentation websites
    2. Sharp - Image transformation library used by Astro
  3. Cypress - End-to-end testing framework
  4. Stylelint - CSS linter used locally in text editors and remotely in CI for testing
    1. stylelint-config-recommended - Base set of lint rules
    2. postcss-html - PostCSS syntax for parsing HTML (and HTML-like including .astro files)
    3. stylelint-config-html - Allows Stylelint to parse .astro files
  5. Prettier - Source code formatter used locally in text editors and remotely in CI for testing
    1. prettier-plugin-astro - Allows Prettier to parse .astro files via the command line

Local development

Run Tech Docs locally by cloning the Tech Docs repository, installing project dependencies, and spinning up a development server:

Terminal window
# Requires git and Node.js


# Clone Tech Docs and move to it
git clone https://github.com/archivesspace/tech-docs.git
cd tech-docs


# Install dependencies
npm install


# Run dev server
npm start

Now go to localhost:4321 to see Tech Docs running locally. Changes to the source code will be immediately reflected in the browser.

Building the site

Building the site creates a set of static files, found in dist after build, that can be served locally or deployed to a server. Sometimes building the site surfaces errors not found in the development environment.

Terminal window
# Build the site and output it to dist/
npm run build

Available npm scripts

The following scripts are made available via package.json. Invoke any script on the command line from the project root by prepending it with the npm run command, ie: npm run start.

  • start — run Astro dev server
  • build — build Tech Docs for production
  • preview — serve the static build
  • astro — get Astro help
  • test:dev — run tests in development mode
  • test:prod — run tests in production mode
  • test — defaults to run tests in production mode
  • prettier:check — check formatting with Prettier
  • prettier:fix — fix possible format errors with Prettier
  • stylelint:check — lint CSS with Stylelint
  • stylelint:fix — fix possible CSS lint errors with Stylelint

Site search is a Starlight feature:

By default, Starlight sites include full-text search powered by Pagefind, which is a fast and low-bandwidth search tool for static sites.

No configuration is required to enable search. Build and deploy your site, then use the search bar in the site header to find content.

Theme customization

Starlight can be customized in various ways, including:

Static assets

Images

Most image files should be stored in src/images. This allows for processing by Astro which includes performance optimizations.

Images that should not be processed by Astro, like favicons, should be stored in public.

The public directory

Files placed in public are not processed by Astro. They are copied directly to the output and made available from the root of the site, so public/favicon.svg becomes available at docs.archivesspace.org/favicon.svg, while public/example/slides.pdf becomes available at docs.archivesspace.org/example/slides.pdf.

Update npm dependencies

Run the following commands locally to update the npm dependencies, then push the changes upstream.

Terminal window
# List outdated dependencies
npm outdated


# Update dependencies
npm update

Import aliases

Astro supports import aliases which provide shortcuts to writing long relative import paths.

src/components/overrides/Example.astro
---
import relativeA from '../../images/A_logo.svg' // no alias
import aliasA from '@images/A_logo.svg' // alias
---

Sitemap

Starlight has built-in sitemap support which is enabled via the top-level site key in astro.config.mjs. This key generates /sitemap-index.xml and /sitemap-0.xml when Tech Docs is built, and adds the sitemap link to the <head> of every page. public/robots.txt also points to the sitemap.

Testing

End-to-end

Tech Docs uses Cypress for end-to-end testing customizations made to the underlying Starlight framework and other project needs. End-to-end tests are located in cypress/e2e.

Run the Cypress tests locally by first building and serving the site:

Terminal window
# Build the site
npm run build


# Serve the build output
npm run preview

Then in a different terminal initiate the tests:

Terminal window
# Run the tests
npm test

Code style

Nearly all files in the Tech Docs code base get formatted by Prettier to ensure consistent readability and syntax. Run Prettier locally to find format errors and automatically fix them when possible:

Terminal window
# 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 to help avoid errors and enforce conventions. Run Stylelint locally to find lint errors and automatically fix them when possible:

Terminal window
# Check all CSS
npm run stylelint:check


# Fix any errors that can be overwritten automatically
npm run stylelint:fix

CI/CD

Before new changes are accepted into the code base, the end-to-end and code style tests need to pass. Tech Docs uses GitHub Actions for its continuous integration and continuous delivery (CI/CD) platform, which automates the testing and deployment processes. The tests are defined in yaml files found in .github/workflows/ and are run automatically when new changes are proposed.