Project structure and development

Git repository

This project is hosted on GitHub at Monash-Emerging-Tech/quantum-computing-edu.

Running & building

First clone the respository and install npm packages:

git clone https://github.com/Monash-Emerging-Tech/quantum-computing-edu.git
cd quantum-computing-edu/quantum-computing-edu-next
npm install
cd ..

To run the Next JS website for development purposes, execute the run-dev Bash script in the repository root.

To build the Next JS website, execute the build Bash script, which produces a static website as output in quantum-computing-edu-next/dist/production/.

The build script also builds the website for deployment on GitHub pages. A .nojekyll file is added by the script to ensure that the site is deployed correctly.

Schemas

The JSON schemas defining the data formats to store circuits and gates in are located in /schemas.

Site source & structure

The Next JS project root is /quantum-computing-edu-next.

Packages

The Next JS site uses the following notable packages:

• @next/mdx
  • with rehype-mathjax
  • and remark-math
• nextjs-mathjax
• mathjs

Package configuration

next.config.ts is modified as follows:

• includes 'md' and 'mdx' page extensions;
• activates the remark-math and rehype-mathjax mdx plugins;
• specifies that the site should be exported as a static site when built;
• defines destination directories for builds.

The "scripts" section in package.json is modified to include a definition for the GitHub pages build script.

tsconfig.json specifies some TypeScript options, all of which are left as reasonable defaults.

mdx-components.tsx can specify custom mdx behaviour, but is currently unmodified (there are no custom components or behaviour defined).

Environment files

.env.development is used by npm run dev, and specifies NEXT_PUBLIC_BUILD and NEXT_PUBLIC_BASEPATH accordingly.

.env.production is used by npm run build, and specifies NEXT_PUBLIC_BUILD accordingly. Currently it defines NEXT_PUBLIC_BASEPATH assuming that the site is hosted within a subdirectory /quantum-computing-edu. You may wish to edit this file for static site testing on your local machine.

.env.gh-pages is used by npm run build:gh-pages, and specifies NEXT_PUBLIC_BUILD and NEXT_PUBLIC_BASEPATH accordingly.

Main page

The current main page is a work-in-progress, with a page index as a placeholder. This page needs to become a proper introductory page, with links to getting-started documentation and notable circuits.

Circuit data

The two files app/circuit-data/circuit-parsing.ts and app/circuit-data/data-loading.ts define functions that handle loading circuit data from JSON files and parsing it into relevant objects.

app/circuit-data/circuits/ stores quantum circuit definitions in the data format defined by /schemas/quantum-circuit-schema.json.

app/circuit-data/gates/ stores quantum gate definitions in the data format defined by /schemas/quantum-gate-schema.json.

app/circuit-data/page-information/ stores markdown files that contain information on gates and circuits. When the site is built, these files are converted into pages attached to the gate and circuit definitions.

app/circuit-data/popup-descriptions/ stores smaller markdown files that contain information on gates and circuits to be displayed in popups opened from the interactive circuit interface. These are generally cut-down copies from app/circuit-data/page-information/.

Circuit pages

app/circuits/[slug]/page.tsx is a dynamic route that is populated when the site is built.

Each circuit defined in app/circuit-data/circuits/ gets one page that displays the circuit in the interactive interface with information about it from app/circuit-data/page-information/.

Gate pages

app/gates/[slug]/page.tsx is a dynamic route that is populated when the site is built.

Each gate defined in app/circuit-data/gates/ gets one page that displays the definition of the gate with information about it from app/circuit-data/page-information/.

Components

app/components/circuit.tsx defines the interactive circuit interface component.

app/components/gate.tsx defines the operation components used in the interactive circuit interface.

app/components/info_bubbles.tsx defines the popup components included in the interactive circuit interface.

Info bubbles use components defined in app/components/popover.tsx, which is from Floating UI (also licensed under MIT).

app/components/matrix.tsx defines a component that parses the stringified form of a matrix definition and displays it in a nice format using NextJS MathJax.

app/components/side_index.tsx defines the components used in the page index that is displayed on the left side of the page.

Meta documentation

app/doc-data/ contains documentation stored in markdown format that informs users and developers about various parts of this project and website. That includes this very documentation you're reading now!

app/docs/[slug]/page.tsx is a dynamic route that is populated when the site is built.