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:
  • remark-math;
  • rehype-mathjax;
  • rehype-citation;
• nextjs-mathjax
• mathjs

Package configuration

next.config.ts is modified as follows:

• includes 'md' and 'mdx' page extensions;
• activates the remark and rehype plugins with their respective options;
• 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 defines custom mdx components and styles.

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

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

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

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.

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 of 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 data/circuits/ gets one page that displays the circuit in the interactive interface with information about it from 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 data/gates/ gets one page that displays the definition of the gate with information about it from data/page-information/.

Components

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

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

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

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

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.

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

Meta documentation

data/docs/ 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.

Citation and referencing

citation/ contains the style files (in CSL format) that define the citation style used on this site. Currently citation/ieee.csl is used for IEEE format.

BibTeX citation entries can be inserted into data/references.bib. These entries are defined globally for the site, so they can be referenced from any page.

Shared functionality code

The lib/ directory contains code that may be used in multiple areas of the project, and could be used outside of the project as well.

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

Similarly, lib/load-docs-list.ts defines functions that handle loading meta documentation data to create a list of corresponding pages.