Documentation for UQ Research Computing Centre (RCC) platforms, built with Astro and Starlight.

Sites and preview links

Site	Folder	Production	Site preview
XNAT	sites/xnat	https://docs.xnat.rcc.uq.edu.au	https://uq-rcc-xnat.pages.dev
Pitschi	sites/pitschi	Not yet published	https://uq-rcc-pitschi.pages.dev
HPC	sites/hpc	Not yet published	https://uq-rcc-hpc.pages.dev

Note

Site previews always show the latest version of main. Production only changes when someone runs Promote to production.

Editing a page using GitHub

Note

If you do not have write access to this repository, GitHub automatically asks you to fork it first, and your change gets submitted as a pull request.

1. Go to the page on its site preview and select Edit page at the bottom. GitHub opens the page's source file in its editor.
2. Make your changes. Use the Preview tab to check the formatting.
3. Select Commit changes, add a short message, and choose Commit directly to the main branch. The site preview updates in 1 to 2 minutes. The live site only changes when someone runs Promote to production.

To have a change reviewed before it reaches main, see Site development with branches and pull requests.

Every page starts with a frontmatter block like this:

---
title: Page title
---

The page content starts here.

Keep this block when you edit a page. A page without a title stops the whole site from building.

Site development with branches and pull requests

To review a change before it reaches main, choose Create a new branch for this commit and start a pull request when you commit, then open the pull request.

• The pull request builds a branch preview at https://<branch>.uq-rcc-<site>.pages.dev, where <branch> is the branch name in lower case.
• A panel at the top of the pull request description shows the build's progress, then links to the branch preview and to a preview of that exact commit.
• Every further push to the branch updates the branch preview and the panel.
• Merging the pull request brings the change into main and updates the site preview. Production still only changes when someone runs Promote to production.

To get a branch preview without a pull request, run the Preview workflow for it from the Actions tab.

Running the sites locally

Install once from the repository root, then run Astro from the site's folder:

npm install
cd sites/<site>
npx astro dev          # start the site at http://localhost:4321
npx astro build        # build the site to dist/
npx astro check        # type-check the site
npx astro preview      # preview the production build
node ../../.github/scripts/check-links.mjs dist   # check internal links and redirects

The dev server keeps running in the background after the command returns. Stop it with npx astro dev stop from the same folder. The npm run scripts in the root package.json run the XNAT site.

Repository structure

sites/
├── xnat/
│   ├── astro.config.mjs     site config, sidebar and legacy redirects
│   ├── public/              static files
│   └── src/
│       ├── content/docs/    pages and colocated images
│       ├── components/      site components
│       └── styles/          site styling
├── pitschi/
│   ├── astro.config.mjs     site config
│   └── src/
│       ├── content/docs/    pages and images
│       └── components/      navbar links
└── hpc/
    ├── astro.config.mjs     site config and sidebar
    └── src/content/docs/    pages, with guides/ and policy/ sections
shared/                      navbar shared by every site
.github/workflows/           Build, Preview and Promote to production
.github/scripts/             link checker and preview panel