MyST Theme by QUT

This is a forked version of myst-theme by Jupyter Book with QUT branding. Including:

• QUT Logo
• QUT Header & Footer Colours
• QUT Acknowledgements, TEQSA & CRICOS

Packages for creating MyST websites themes using React and Remix.

The MyST Theme components documentation is the best way to visualize the style and structure of components.

Git Workflow

This section will walk you through on how to:

• Create branch
• Commit & Push your changes
• Get your branch reviewed and merged
• Create a release on latest version

Create branch

Make sure you are on the latest main branch Use the following command to check which branch you are on:

  git branch

Then, create and checkout your branch:

  git branch <branch-name>
  git checkout <branch-name>

Or combine the two steps with:

  git checkout -b <branch-name>

Commit & Push your changes

Make sure you are on correct branch, to check:

  git branch

Then, check the list of the files you modified:

  git status

To check all your changes on one or all files in detail, use:

  git diff <specific-file-path (optional)>

Once you are happy with your changes, use following command to stage your changes on one or all files

  git add . or <specific-file-path>

Once you finished staging files, commit your changes with:

  git commit -m "<your commit message>"

Get your branch reviewed and merged

At this stage, you should already have your worked branch with your latest commit. So far, all your changes happened on your local workspace and machine. So you will need to push your branch to remote repository.

To push your branch, use:

  git push -u origin <branch-name>

Now, your branch should be on your remote repository, to create a pull request, follow the instructions in here. Once your branch is approved, you or the code reviewer will merged the branch into main branch.

Create a release on latest version

[IMPORTANT]

technical-docs is using latest release of this repository, please make sure you understand what you are doing before doing release.

Congratulations on merging your first branch (assume you just did it for first time). Now, you may want to create a new release which contains your latest changes.

Again, make sure your are on correct branch. In this case, main, which you just merged your latest changes.

To create a new release on Github, create a new tag by using:

  git tag -a <tag_name> -m "<your-new-release-message>"

Then, push the new tag to Github:

  git push origin <tag_name>

If you are using GitHub CLI, follow the instructions in here.

(Advanced) Additionally, if your tag is already existed, in this repo, it will likely be latest. To override:

  git push origin latest --force

FAQ

Q: Why working on a branch is a better practice over directly on main branch?

A: Creating a branch and working on it instead of pushing directly to the main branch is considered a best practice in version control systems like Git. Here’s why and a comparison table between:

Aspect	Working in a Branch	Pushing Directly to Main
Code Isolation	Changes are isolated and tested separately.	Changes are made directly to the main branch.
Risk of Breaking Code	Minimal risk to the main branch.	High risk of breaking the main branch.
Code Review	Facilitates collaboration and thorough reviews.	No review process, leading to potential errors.
Feature Development	Enables parallel development of multiple features.	Difficult to coordinate multiple changes.
Rollback	Easier to revert or discard changes in a branch.	Rollbacks may be messy or disruptive.
Continuous Integration	Supports automated testing and quality checks.	Tests may fail on the main branch, disrupting others.
Collaboration	Encourages team collaboration without conflicts.	Direct changes may overwrite others' work.
Commit History	Maintains a clean and organized history.	May lead to a cluttered commit history.

Q: Why creating release over manually downloading all files from the repository?

A: Creating a release in a version control system like Github is more advantageous than simply providing a manual download of the files. Here's why and a comparison table between:

Aspect	Creating a Release	Manual Download
Versioning	Automatically versioned and tied to commits.	No versioning or tracking.
Source of Truth	Linked to a specific commit; reliable.	Prone to errors in file selection.
Ease of Access	Pre-packaged and ready to download.	Requires manual preparation of files.
Reproducibility	Ensures exact replication of the codebase.	Difficult to replicate manually.
CI/CD Integration	Supports automated testing and deployment.	No testing or deployment automation.
Professionalism	Demonstrates a polished, user-friendly approach.	Feels ad-hoc and unorganized.
Notifications	Automatic notifications for new releases.	Users must be notified manually.
Security	Files are verified and secure.	Files may lack integrity verification.

Development

All dependencies for myst-theme are included in this repository (a monorepo!). The core themes are also included in this repository to aid in development.

What's inside?

Components:

• myst-to-react: expose MyST content as an article, built with React
• @myst-theme/frontmatter: Show title, authors and affiliations
• @myst-theme/providers: React providers for references and site configuration
• @myst-theme/demo: myst-demo component for showing syntax
• @myst-theme/diagrams: mermaid diagrams for MyST
• @myst-theme/icons: MyST icons for React
• @myst-theme/site: components and utilities for building Remix sites

Styles:

• @myst-theme/styles: Reusable style components using tailwind

Themes:

• @myst-theme/book: Designed to mimic the look-and-feel of an interactive book.
• @myst-theme/article: A single-page view of an article with associated notebooks or supporting sub-articles.

Versioning & Publishing

myst-theme uses changesets to document changes to this monorepo, call npm run changeset and follow the prompts. Later, npm run version will be called and then npm run publish.

Utilities

myst-theme is built and developed using:

• React for component rendering
• TypeScript for static type checking
• ESLint for code linting
• Prettier for code formatting
• Tailwind for styling
• Storybook for documenting components

Development

This repository depends on themes which are brought in as a sub-module. When first cloning the repository use git clone --recursive, then install the various dependencies:

git clone --recursive https://github.com/executablebooks/myst-theme.git
cd myst-theme
npm install

Recommended VSCode Extensions

• Headwind: sorts the tailwind class names

Build

To build all themes and packages, run the following command:

npm run build

Develop

These packages are best shown using storybook a UI library that powers the docs. This is the same tool that powers the MyST Theme components documentation.

npm run storybook
# and in another terminal
npm run dev

Working with themes

To interact with the themes in development mode (e.g. with live-reload of components and styles as you are making changes), you need three things running:

1. a content server
2. the renderer/application (theme)
3. a process watching all components

# In a directory with content
myst start --headless
# In myst-theme
npm run theme:book
# In another terminal, watch for changes and rebuild
npm run dev

Note: in the future, this repository will likely have it's own content to test out with the themes. You can currently look to the mystjs/docs folder, or an article or a thesis.

To run on a specific port (for example, developing locally between two projects), you can specify a custom port with:

myst start --headless --server-port 3111
CONTENT_CDN_PORT=3111 npm run theme:book

To connect to a remote content server, set the CONTENT_CDN environment variable:

CONTENT_CDN=https://remote.example.com npm run theme:book
CONTENT_CDN=https://remote.example.com npm run theme:article

Deployment

To update the theme components on NPM:

npm run version
npm run publish

To update the themes for use with the MyST CLI:

make deploy-book
make deploy-article

This updates the git repository, and sometimes is a large diff and can cause git to hang, if that happens this command can help change the buffer size when sending the diff to GitHub:

git config --global http.postBuffer 157286400