Functional Requirements

The core functionality of our browser-based WYSIWYG (What You See Is What You Get) editor centers on delivering a smooth and accessible editing experience. It must allow users to edit content directly on the rendered book page. the editor should support Markdown, MyST-MD, and basic Sphinx syntax so users can create and format their content correctly. For example, users should be able to make text bold or italic, create headings, and add bullet points using a Word-like toolbar. The toolbar must also let users insert and edit different types of content, such as text blocks, code blocks, and images. These features should be easy to use and appear directly above or around the selected content.

The tool must work fully inside the web browser, without relying on any server or backend system. This means everything should happen on the client side, so the TeachBooks platform can stay free of server costs. To prevent users from losing their work, the tool must automatically save any unsaved changes locally in the browser. This way, if someone accidentally refreshes the page or closes it, their changes will still be there the next time they return.

GitHub integration is one of the most important features. Users must be able to log in using either GitHub OAuth or a personal access token. After making changes, they should be able to either commit them directly to a selected branch or create a pull request. The interface must clearly show which branch they are working on at all times. There should also be visual feedback to show which parts of the book have been edited and saved to GitHub.

The editor should also help users understand how GitHub works. This includes teaching them about keyboard navigation, branches, commits, and the authentication process. If a user tries to do something the editor cannot support directly—such as changing configuration files or using advanced syntax—it must show a tutorial or help window that explains how to do this using other tools or directly on GitHub.

To ensure the editor works well with existing projects, it must follow the directory structure, file naming rules, and syntax used in Jupyter Book and Sphinx. This means users can edit a book in the browser, then continue working on it using other tools like VS Code without any problems. The saved files must still build correctly with jupyter-book build.

The final mandatory requirement for this project is that the codebase must be well-structured and easy to maintain. Developers who want to add new features in the future—such as support for more Sphinx directives or collaboration tools—should be able to do so without rewriting everything. The structure should be modular and use common development practices so that others can read and improve the code easily.

Secondary but important features include better accessibility through WCAG 2.1–aligned design.[KCCC18] This means the editor should support keyboard navigation, use colorblind-friendly palettes, and follow best practices to ensure it is usable by people with different abilities. The toolbar should adjust dynamically based on the type of content being edited. In addition, users should be able to insert common interactive elements such as exercises and solution blocks. Full book editing in the browser is a long-term goal, however, certain advanced tasks may still require switching to GitHub.

Finally, optional—but still desirable—capabilities include LaTeX rendering for math expressions, both inline and in blocks, to support subjects that rely on mathematical notation. Over time, features such as collaborative editing or integration with GitLab could be considered. However, the tool must not try to replace key GitHub functionality like merging branches. For important tasks such as reviewing pull requests or resolving merge conflicts, the editor should guide users back to GitHub and explain why those actions need to happen there.