Skip to content

Commit 7a51910

Browse files
aswinnarayananaswinnarayanan
committed
Migrate docs from Hugo Docsy to Astro Starlight
- Port all content; convert Docsy shortcodes (alert/pageinfo/card) to Starlight asides and cards, and procedures to Steps - Reimplement the interactive email request forms as Astro components - Restructure for clarity: - Getting Started is one tabbed page by member type (UQ / Other AAF / Non-AAF), with explainer cards and shareable ?member= links - Logging into XNAT consolidated into a single AAF / RCC Authenticate page - Alias tokens moved to Processing Data (it is external-tool auth) - CTP Windows and Linux service pages merged into one OS-tabbed page - Scans folded into the Sessions overview - Empty section landings given an intro and card grid - UQ purple theme, restyled navbar search, cycling light/dark/auto toggle - Preserve every old Hugo /docs/... URL (and legacy aliases) via redirects - Build and deploy to GitHub Pages with Node 20 instead of Hugo
1 parent 2abf60f commit 7a51910

165 files changed

Lines changed: 8713 additions & 2879 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/gh-pages.yml‎

Lines changed: 8 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -3,49 +3,29 @@ name: github pages
33
on:
44
push:
55
branches:
6-
- main # Set a branch to deploy
6+
- main # Set a branch to deploy
77
pull_request:
88

99
jobs:
1010
deploy:
1111
runs-on: ubuntu-22.04
1212
steps:
13-
- uses: actions/checkout@v2
14-
with:
15-
submodules: recursive # Fetch Hugo themes (true OR recursive)
16-
fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
17-
18-
- name: Setup Hugo
19-
uses: peaceiris/actions-hugo@v3
20-
with:
21-
hugo-version: 'latest'
22-
extended: true
13+
- uses: actions/checkout@v4
2314

2415
- name: Setup Node
25-
uses: actions/setup-node@v2
16+
uses: actions/setup-node@v4
2617
with:
27-
node-version: '16'
28-
29-
- name: Cache dependencies
30-
uses: actions/cache@v4
31-
with:
32-
path: ~/.npm
33-
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
34-
restore-keys: |
35-
${{ runner.os }}-node-
18+
node-version: '20'
19+
cache: 'npm'
3620

3721
- run: npm ci
38-
39-
- name: Build
40-
run: hugo --minify
4122

42-
- name: Add custom domain
43-
if: github.repository == 'UQ-RCC/xnat'
44-
run: cp ./static/CNAME ./public/CNAME
23+
- name: Build
24+
run: npm run build
4525

4626
- name: Deploy
4727
uses: peaceiris/actions-gh-pages@v3
4828
if: github.ref == 'refs/heads/main'
4929
with:
5030
github_token: ${{ secrets.GITHUB_TOKEN }}
51-
publish_dir: ./public
31+
publish_dir: ./dist

‎.gitignore‎

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
1-
/public
2-
resources/
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
# dependencies
36
node_modules/
4-
# package-lock.json
5-
hugo.exe
6-
AGENTS.md
7+
# environment
8+
.env
9+
.env.production
10+
# macOS
11+
.DS_Store
12+
AGENTS.md

‎.gitmodules‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎.hugo_build.lock‎

Whitespace-only changes.

‎Dockerfile‎

Lines changed: 0 additions & 3 deletions
This file was deleted.

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,22 @@
11
_Information on the **UQ-RCC XNAT** is available at [docs.xnat.rcc.uq.edu.au](https://docs.xnat.rcc.uq.edu.au)_
2+
3+
---
4+
5+
This documentation site is built with [Astro](https://astro.build) and [Starlight](https://starlight.astro.build).
6+
7+
## Local development
8+
9+
```
10+
npm install
11+
npm run dev # start a dev server at http://localhost:4321
12+
npm run build # build the production site to ./dist
13+
npm run preview # preview the production build locally
14+
```
15+
16+
## Structure
17+
18+
- `src/content/docs/` — documentation pages (Markdown / MDX), colocated with their images
19+
- `src/components/` — interactive components (email request forms)
20+
- `src/styles/custom.css` — UQ purple theme overrides
21+
- `astro.config.mjs` — site config, sidebar and redirects from the old Hugo `/docs/` URLs
22+
- `public/CNAME` — custom domain

‎assets/scss/_variables_project.scss‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎astro.config.mjs‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
// @ts-check
2+
import { defineConfig } from 'astro/config';
3+
import starlight from '@astrojs/starlight';
4+
5+
// Every content page's slug (used to redirect the old Hugo `/docs/...` URLs).
6+
const slugs = [
7+
'user-guides',
8+
'user-guides/faq',
9+
'user-guides/getting-started',
10+
'user-guides/logging-into-xnat',
11+
'user-guides/using-xnat',
12+
'user-guides/using-xnat/projects',
13+
'user-guides/using-xnat/projects/granting-access',
14+
'user-guides/using-xnat/projects/request-storage',
15+
'user-guides/using-xnat/subjects',
16+
'user-guides/using-xnat/sessions',
17+
'user-guides/using-xnat/search',
18+
'user-guides/managing-data',
19+
'user-guides/managing-data/downloading-data',
20+
'user-guides/managing-data/downloading-data/zip-download',
21+
'user-guides/managing-data/downloading-data/desktop-client',
22+
'user-guides/managing-data/downloading-data/download-scan',
23+
'user-guides/managing-data/viewing-images',
24+
'user-guides/managing-data/uploading-data',
25+
'user-guides/managing-data/uploading-data/web-upload',
26+
'user-guides/managing-data/uploading-data/resource-uploader',
27+
'user-guides/managing-data/uploading-data/prearchive',
28+
'user-guides/managing-data/syncing-data',
29+
'user-guides/managing-data/anonymising-data',
30+
'user-guides/managing-data/anonymising-data/project-anonymiser',
31+
'user-guides/managing-data/anonymising-data/site-anonymiser',
32+
'user-guides/processing-data',
33+
'user-guides/processing-data/command-line-tools',
34+
'user-guides/processing-data/interactive-analysis',
35+
'facility-guides',
36+
'facility-guides/ctp',
37+
'facility-guides/ctp/installation',
38+
'facility-guides/ctp/proxy-server',
39+
];
40+
41+
// Old Hugo `/docs/<slug>` -> new `/<slug>`, plus the legacy Hugo aliases.
42+
const redirects = {
43+
'/docs': '/',
44+
...Object.fromEntries(slugs.map((s) => [`/docs/${s}`, `/${s}`])),
45+
// Getting Started was split into per-member pages; it's now a single tabbed
46+
// page that selects the member type via a `?member=` query param. Redirect
47+
// every old per-member URL (both the Astro and original Hugo `/docs/` forms)
48+
// and the legacy Hugo aliases to the matching tab.
49+
'/user-guides/getting-started/uq-members':
50+
'/user-guides/getting-started/?member=uq-members',
51+
'/user-guides/getting-started/other-aaf-members':
52+
'/user-guides/getting-started/?member=other-aaf-members',
53+
'/user-guides/getting-started/non-aaf-members':
54+
'/user-guides/getting-started/?member=non-aaf-members',
55+
'/user-guides/getting-started/hirf-users': '/user-guides/getting-started/',
56+
'/docs/user-guides/getting-started/uq-members':
57+
'/user-guides/getting-started/?member=uq-members',
58+
'/docs/user-guides/getting-started/other-aaf-members':
59+
'/user-guides/getting-started/?member=other-aaf-members',
60+
'/docs/user-guides/getting-started/non-aaf-members':
61+
'/user-guides/getting-started/?member=non-aaf-members',
62+
'/docs/user-guides/getting-started/hirf-users': '/user-guides/getting-started/',
63+
64+
// The standalone "AAF login" page was merged into the Logging into XNAT
65+
// overview (AAF tab). Alias tokens moved to Processing Data (it's about
66+
// authenticating external tools, not website login).
67+
'/user-guides/logging-into-xnat/aaf-login': '/user-guides/logging-into-xnat/',
68+
'/docs/user-guides/logging-into-xnat/aaf-login': '/user-guides/logging-into-xnat/',
69+
'/user-guides/logging-into-xnat/alias-tokens':
70+
'/user-guides/processing-data/alias-tokens',
71+
'/docs/user-guides/logging-into-xnat/alias-tokens':
72+
'/user-guides/processing-data/alias-tokens',
73+
74+
// Scans folded into the Sessions overview.
75+
'/user-guides/using-xnat/sessions/scans':
76+
'/user-guides/using-xnat/sessions/#viewing-scans',
77+
'/docs/user-guides/using-xnat/sessions/scans':
78+
'/user-guides/using-xnat/sessions/#viewing-scans',
79+
80+
// CTP Windows/Linux service pages merged into one OS-tabbed page.
81+
'/facility-guides/ctp/windows-service': '/facility-guides/ctp/run-as-service',
82+
'/facility-guides/ctp/linux-service': '/facility-guides/ctp/run-as-service',
83+
'/docs/facility-guides/ctp/windows-service': '/facility-guides/ctp/run-as-service',
84+
'/docs/facility-guides/ctp/linux-service': '/facility-guides/ctp/run-as-service',
85+
86+
// Legacy aliases declared in the original Hugo front matter.
87+
'/docs/user-guides/create-xnat-project': '/user-guides/getting-started',
88+
'/docs/user-guides/create-xnat-project/create-q-collection-uq-users':
89+
'/user-guides/getting-started/?member=uq-members',
90+
'/docs/user-guides/create-xnat-project/create-q-collection-non-uq-users':
91+
'/user-guides/getting-started/?member=other-aaf-members',
92+
'/docs/user-guides/browsing-xnat': '/user-guides/using-xnat',
93+
'/docs/user-guides/login-to-xnat': '/user-guides/logging-into-xnat',
94+
'/docs/user-guides/login-to-xnat/aaf-login': '/user-guides/logging-into-xnat/',
95+
};
96+
97+
// https://astro.build/config
98+
export default defineConfig({
99+
site: 'https://docs.xnat.rcc.uq.edu.au',
100+
redirects,
101+
integrations: [
102+
starlight({
103+
title: 'UQ AIS XNAT',
104+
description:
105+
'Storing, managing and analysing de-identified imaging data for UQ projects and collaborators',
106+
customCss: ['./src/styles/custom.css'],
107+
tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 },
108+
components: {
109+
// Replace the header's social-icons slot with our top-nav links.
110+
SocialIcons: './src/components/NavLinks.astro',
111+
// Cycling theme toggle (auto → light → dark) instead of the dropdown.
112+
ThemeSelect: './src/components/ThemeSelect.astro',
113+
},
114+
sidebar: [
115+
{
116+
label: 'User Guides',
117+
items: [
118+
// FAQ hidden from the sidebar until it has real content.
119+
// The page still exists at /user-guides/faq (kept for old redirects).
120+
// Getting Started is now a single tabbed page (member type via tabs).
121+
{ label: 'Getting Started', slug: 'user-guides/getting-started' },
122+
// Logging into XNAT is now a single page (AAF + RCC Authenticate tabs).
123+
{ label: 'Logging into XNAT', slug: 'user-guides/logging-into-xnat' },
124+
{
125+
label: 'Using XNAT',
126+
items: [
127+
{ label: 'Overview', slug: 'user-guides/using-xnat' },
128+
{
129+
label: 'Projects',
130+
items: [
131+
{ label: 'Overview', slug: 'user-guides/using-xnat/projects' },
132+
{ label: 'Granting Access', slug: 'user-guides/using-xnat/projects/granting-access' },
133+
{ label: 'Request Storage', slug: 'user-guides/using-xnat/projects/request-storage' },
134+
],
135+
},
136+
{ label: 'Subjects', slug: 'user-guides/using-xnat/subjects' },
137+
{ label: 'Sessions', slug: 'user-guides/using-xnat/sessions' },
138+
{ label: 'Search', slug: 'user-guides/using-xnat/search' },
139+
],
140+
},
141+
{
142+
label: 'Managing Data',
143+
items: [
144+
{
145+
label: 'Downloading Data',
146+
items: [
147+
{ label: 'Overview', slug: 'user-guides/managing-data/downloading-data' },
148+
{ label: 'Zip Download', slug: 'user-guides/managing-data/downloading-data/zip-download' },
149+
{ label: 'Desktop client', slug: 'user-guides/managing-data/downloading-data/desktop-client' },
150+
{ label: 'Download Scan', slug: 'user-guides/managing-data/downloading-data/download-scan' },
151+
],
152+
},
153+
{ label: 'Viewing Images', slug: 'user-guides/managing-data/viewing-images' },
154+
{
155+
label: 'Uploading Data',
156+
items: [
157+
{ label: 'Overview', slug: 'user-guides/managing-data/uploading-data' },
158+
{ label: 'Web Upload', slug: 'user-guides/managing-data/uploading-data/web-upload' },
159+
{ label: 'Resource uploader', slug: 'user-guides/managing-data/uploading-data/resource-uploader' },
160+
{ label: 'Prearchive', slug: 'user-guides/managing-data/uploading-data/prearchive' },
161+
],
162+
},
163+
{ label: 'Syncing Data', slug: 'user-guides/managing-data/syncing-data' },
164+
{
165+
label: 'Anonymising Data',
166+
items: [
167+
{ label: 'Overview', slug: 'user-guides/managing-data/anonymising-data' },
168+
{ label: 'Project anonymiser', slug: 'user-guides/managing-data/anonymising-data/project-anonymiser' },
169+
{ label: 'Site anonymiser', slug: 'user-guides/managing-data/anonymising-data/site-anonymiser' },
170+
],
171+
},
172+
],
173+
},
174+
{
175+
label: 'Processing Data',
176+
items: [
177+
{ label: 'Alias tokens', slug: 'user-guides/processing-data/alias-tokens' },
178+
{ label: 'Command line tools', slug: 'user-guides/processing-data/command-line-tools' },
179+
{ label: 'Interactive Analysis', slug: 'user-guides/processing-data/interactive-analysis' },
180+
],
181+
},
182+
],
183+
},
184+
{
185+
label: 'Facility Guides',
186+
items: [
187+
{
188+
label: 'Clinical Trials Processor (CTP)',
189+
items: [
190+
{ label: 'Overview', slug: 'facility-guides/ctp' },
191+
{ label: 'Installation', slug: 'facility-guides/ctp/installation' },
192+
{ label: 'Run CTP as a service', slug: 'facility-guides/ctp/run-as-service' },
193+
{ label: 'Proxy Server Settings', slug: 'facility-guides/ctp/proxy-server' },
194+
],
195+
},
196+
],
197+
},
198+
],
199+
}),
200+
],
201+
});

0 commit comments

Comments
 (0)