Development and maintenance

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 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 package.json for current version information):

1. Node.js - JavaScript development and build environment
2. Astro - Static site generator conceptually based on “components” (React, Vue, Svelte, etc.) rather than “templates” (Handlebars, Pug, Haml, etc.)
3. Starlight - Astro plugin and theme for documentation websites
4. Sharp - Image transformation library used by Astro
5. Prettier - Source code formatter used locally in text editors and in CI for testing and build purposes

Local development

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

# 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 src/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.

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

Search

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.

Note

Tech Docs search does not run in local development.

Theme customization

Starlight can be customized in various ways, including:

• Settings — see astro.config.mjs
• CSS — see src/styles/custom.css
• UI components — see src/components

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.

Use src/images for all content images

Put all images used in Tech Docs content in src/images.

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.

# List outdated dependencies
npm outdated

# Update dependencies
npm update