Skip to content

Commit 86588eb

Browse files
chrisnschrisns
authored
Add Docusaurus documentation site with Mermaid support (#1)
* feat: Add Docusaurus documentation site with Mermaid support - Add Docusaurus 3.5.2 site in website/ directory - Configure Mermaid diagram rendering with @docusaurus/theme-mermaid - Add GitHub Actions workflow for GitHub Pages deployment - Add Dependabot configuration with grouped updates - Add prepare-docs.js script to transform docs at build time: - Adds frontmatter (id, title, sidebar_position) - Escapes MDX special characters ({}, <>) - Source docs remain unchanged - transformation happens at build - Update .gitignore for website build artifacts Run locally with: cd website && npm install && npm start * fix: Update footer to GDS/DSIT and add build info with git SHA link * ci: Temporarily deploy from feature branch for testing * feat: Redirect homepage to /docs/ * fix: Use useBaseUrl for redirect to respect baseUrl * ci: Restore main-only deployment * ci: Run build on PRs, deploy only on main * docs: add documentation site link to README Add link to browse the documentation at https://co-cddo.github.io/ndx-try-arch/ * ci: Add merge_group trigger for merge queue support The merge queue requires workflows to listen for the merge_group event to run checks on the temporary merge branch.
1 parent c244fdb commit 86588eb

27 files changed

Lines changed: 18240 additions & 0 deletions

‎.github/dependabot.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
version: 2
2+
updates:
3+
# NPM dependencies for Docusaurus website
4+
- package-ecosystem: "npm"
5+
directory: "/website"
6+
schedule:
7+
interval: "weekly"
8+
day: "monday"
9+
time: "09:00"
10+
timezone: "Europe/London"
11+
groups:
12+
docusaurus:
13+
patterns:
14+
- "@docusaurus/*"
15+
- "docusaurus"
16+
update-types:
17+
- "minor"
18+
- "patch"
19+
react:
20+
patterns:
21+
- "react"
22+
- "react-dom"
23+
- "@types/react*"
24+
prism:
25+
patterns:
26+
- "prism-react-renderer"
27+
- "@types/prismjs"
28+
dev-dependencies:
29+
dependency-type: "development"
30+
update-types:
31+
- "minor"
32+
- "patch"
33+
commit-message:
34+
prefix: "chore(deps)"
35+
labels:
36+
- "dependencies"
37+
- "documentation"
38+
open-pull-requests-limit: 5
39+
reviewers:
40+
- "co-cddo/ndx-maintainers"
41+
42+
# GitHub Actions dependencies
43+
- package-ecosystem: "github-actions"
44+
directory: "/"
45+
schedule:
46+
interval: "weekly"
47+
day: "monday"
48+
time: "09:00"
49+
timezone: "Europe/London"
50+
groups:
51+
actions:
52+
patterns:
53+
- "*"
54+
commit-message:
55+
prefix: "chore(ci)"
56+
labels:
57+
- "dependencies"
58+
- "ci/cd"
59+
open-pull-requests-limit: 3

‎.github/workflows/deploy-docs.yml‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
name: Deploy Documentation
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- 'docs/**'
8+
- 'website/**'
9+
- '.github/workflows/deploy-docs.yml'
10+
pull_request:
11+
paths:
12+
- 'docs/**'
13+
- 'website/**'
14+
- '.github/workflows/deploy-docs.yml'
15+
merge_group:
16+
workflow_dispatch:
17+
18+
permissions:
19+
contents: read
20+
pages: write
21+
id-token: write
22+
23+
concurrency:
24+
group: ${{ github.workflow }}-${{ github.ref }}
25+
cancel-in-progress: true
26+
27+
jobs:
28+
build:
29+
runs-on: ubuntu-latest
30+
steps:
31+
- name: Checkout
32+
uses: actions/checkout@v4
33+
34+
- name: Setup Node.js
35+
uses: actions/setup-node@v4
36+
with:
37+
node-version: '20'
38+
cache: 'npm'
39+
cache-dependency-path: website/package-lock.json
40+
41+
- name: Install dependencies
42+
working-directory: website
43+
run: npm ci
44+
45+
- name: Build website
46+
working-directory: website
47+
run: npm run build
48+
49+
- name: Setup Pages
50+
if: github.ref == 'refs/heads/main'
51+
uses: actions/configure-pages@v5
52+
53+
- name: Upload artifact
54+
if: github.ref == 'refs/heads/main'
55+
uses: actions/upload-pages-artifact@v3
56+
with:
57+
path: website/build
58+
59+
deploy:
60+
if: github.ref == 'refs/heads/main'
61+
environment:
62+
name: github-pages
63+
url: ${{ steps.deployment.outputs.page_url }}
64+
runs-on: ubuntu-latest
65+
needs: build
66+
steps:
67+
- name: Deploy to GitHub Pages
68+
id: deployment
69+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,14 @@ logs/
3232
node_modules/
3333
npm-debug.log*
3434

35+
# Docusaurus website
36+
website/node_modules/
37+
website/build/
38+
website/.docusaurus/
39+
website/.cache-loader/
40+
website/docs/
41+
website/blog/
42+
3543
# Python (if any tooling added)
3644
__pycache__/
3745
*.py[cod]

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Automated architecture documentation for the NDX (National Digital Exchange) Innovation Sandbox ecosystem.
44

5+
📖 **[Browse the documentation](https://co-cddo.github.io/ndx-try-arch/)**
6+
57
## What This System Does
68

79
This repository maintains living documentation of the NDX/ISB infrastructure by:

‎website/.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎website/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
Using SSH:
30+
31+
```
32+
$ USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```
38+
$ GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎website/babel.config.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
module.exports = {
2+
presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
3+
};

‎website/docusaurus.config.ts‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
import {themes as prismThemes} from 'prism-react-renderer';
2+
import type {Config} from '@docusaurus/types';
3+
import type * as Preset from '@docusaurus/preset-classic';
4+
import {execSync} from 'child_process';
5+
6+
// Get build info
7+
const gitSha = process.env.GITHUB_SHA || execSync('git rev-parse HEAD').toString().trim();
8+
const gitShaShort = gitSha.slice(0, 7);
9+
const buildDate = new Date().toISOString().split('T')[0];
10+
11+
const config: Config = {
12+
title: 'NDX Architecture',
13+
tagline: 'NDX Innovation Sandbox Platform Documentation',
14+
favicon: 'img/favicon.ico',
15+
16+
url: 'https://co-cddo.github.io',
17+
baseUrl: '/ndx-try-arch/',
18+
19+
organizationName: 'co-cddo',
20+
projectName: 'ndx-try-arch',
21+
trailingSlash: false,
22+
23+
onBrokenLinks: 'warn',
24+
onBrokenMarkdownLinks: 'warn',
25+
26+
i18n: {
27+
defaultLocale: 'en',
28+
locales: ['en'],
29+
},
30+
31+
markdown: {
32+
mermaid: true,
33+
},
34+
35+
themes: ['@docusaurus/theme-mermaid'],
36+
37+
presets: [
38+
[
39+
'classic',
40+
{
41+
docs: {
42+
sidebarPath: './sidebars.ts',
43+
editUrl: 'https://github.com/co-cddo/ndx-try-arch/tree/main/website/',
44+
},
45+
blog: false,
46+
theme: {
47+
customCss: './src/css/custom.css',
48+
},
49+
} satisfies Preset.Options,
50+
],
51+
],
52+
53+
themeConfig: {
54+
image: 'img/docusaurus-social-card.jpg',
55+
navbar: {
56+
title: 'NDX Architecture',
57+
logo: {
58+
alt: 'NDX Logo',
59+
src: 'img/logo.svg',
60+
},
61+
items: [
62+
{
63+
type: 'docSidebar',
64+
sidebarId: 'docsSidebar',
65+
position: 'left',
66+
label: 'Documentation',
67+
},
68+
{
69+
href: 'https://github.com/co-cddo/ndx-try-arch',
70+
label: 'GitHub',
71+
position: 'right',
72+
},
73+
],
74+
},
75+
footer: {
76+
style: 'dark',
77+
links: [
78+
{
79+
title: 'Documentation',
80+
items: [
81+
{
82+
label: 'Overview',
83+
to: '/docs/',
84+
},
85+
{
86+
label: 'Architecture',
87+
to: '/docs/80-c4-architecture',
88+
},
89+
],
90+
},
91+
{
92+
title: 'Resources',
93+
items: [
94+
{
95+
label: 'GitHub',
96+
href: 'https://github.com/co-cddo/ndx-try-arch',
97+
},
98+
],
99+
},
100+
],
101+
copyright: `Copyright © ${new Date().getFullYear()} Government Digital Service (GDS), DSIT. Built ${buildDate} from <a href="https://github.com/co-cddo/ndx-try-arch/tree/${gitSha}">${gitShaShort}</a>.`,
102+
},
103+
prism: {
104+
theme: prismThemes.github,
105+
darkTheme: prismThemes.dracula,
106+
additionalLanguages: ['bash', 'json', 'yaml', 'typescript'],
107+
},
108+
mermaid: {
109+
theme: {
110+
light: 'neutral',
111+
dark: 'dark',
112+
},
113+
},
114+
} satisfies Preset.ThemeConfig,
115+
};
116+
117+
export default config;

0 commit comments

Comments
 (0)