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.
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.
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:
These are included as submodules, use git clone --recursive when first cloning.
@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.
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.
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
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
- Headwind: sorts the tailwind class names
To build all themes and packages, run the following command:
npm run build
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
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:
- a content server
- the renderer/application (theme)
- 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 devNote: 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:bookTo update the theme components on NPM:
npm run version
npm run publishTo update the themes for use with the MyST CLI:
make deploy-book
make deploy-articleThis 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