mathigon / textbooks

Source code of Mathigon's interactive textbooks

Mathigon Textbooks

Welcome to Mathigon, an award-winning mathematics education platform for students aged 12 to 18. Part textbook and part virtual personal tutor, it uses cutting-edge technology and an innovative new curriculum to make learning mathematics more fun and more interactive and engaging than ever before. Learn more…

This repository contains the source code and assets for all our courses.

Setup

If you want to make changes or additions to this content, you can run a local Node.js server for development. First, make sure you have NPM and Node.js (version 14+) installed on your computer, or download them from the official page.

Next, clone this repository, install all dependencies, and then start a local server using these commands:

git clone https://github.com/mathigon/textbooks
cd textbooks
npm install
npm start

Running npm start for the first time may take a few minutes, as it compiles all existing courses. Later, it should use cached versions whenever possible. Finally, you can visit localhost:5000 and select any of the chapters.

The server will watch for changes to any of the files and recompile automatically whenever necessary (with a few exceptions like shared or YAML files).

Contributing

We welcome any contributions to Mathigon – from bug fixes and correcting typos to creating entirely new courses. If you find any bugs or mistakes, please file an issue.

When writing new content, make sure you follow our content development guide, which contains pedagogical principles, style recommendations, and descriptions of interactive elements.

If you want to help us translate Mathigon into more languages, take a look at our localisation documentation.

Before submitting a pull request, you have to sign our Individual Contributor License Agreement.

If you want to work for Mathigon, visit our careers page, and contact us if you have any questions.

Documentation

Course Structure

Every course is a subfolder in the content directory, and consists of these components:

• content.md contains the source code and metadata for a course. It is written in a custom extension of Markdown. More documentation…
• functions.ts contains all the TypeScript code for all the interactive elements in this course. More documentation…
• styles.scss contains all course-specific styles, written in SCSS.
• hints.yaml (optional) contains any messages that can be sent by Mathigon's virtual tutor.

The content/shared directory contains biographies, glossary, web components, and assets used by multiple courses.

Dependencies

This repository contains all the code and content for our interactive courses. Its dependencies include a number of separate libraries that are published on NPM. In most cases, you should not have to make changes to these libraries directly, but it may be helpful to look at their documentation:

• @mathigon/core contains JavaScript utilities such as array and string manipulation, promises, function caching, and event handling.
• @mathigon/fermat is a powerful mathematics library for TypeScript. It contains everything from number theory to random numbers and linear algebra classes.
• @mathigon/hilbert handles expression parsing, simplification, and MathML rendering.
• @mathigon/euclid contains Geometry classes as well as SVG and Canvas drawing utilities.
• @mathigon/boost contains browser utilities such as DOM selections, web components, gesture recognisers, animations, routing, multi-threading and AJAX requests.
• @mathigon/studio contains the base NodeJS server, TypeScript components and markdown parser for our interactive courses.

Testing and Linting

Before submitting a pull request, make sure to run npm run lint-fix, to ensure a consistent coding style across all files.

TODO: Unit and screendiff tests

Translations and Localisation

Translations are powered by GitLocalize. In order to help us translate content, you have to create a GitHub account and then contact us to be added to the list of editors. This blog post explains how you can use the GitLocalize platform to add new languages, translate new courses, or fix bugs in existing translations.

Audio Narrations

To generate audio narration files for the text in all courses, using the Google Cloud TTS API, you first need to install FFmpeg, for example using brew install ffmpeg. Then simply run node utilities/audio.js.

---

© Mathigon 2016–2022, All rights reserved