CMSC 22000 Final report

Quarter: Spring 2025

Feature: Knowledge Base

Design and Implementation

This quarter, we were tasked with implementing the first iteration of the "Knowledge Base." We implemented the feature as a sub-app of ChiGame that uses existing authentication systems. The Knowledge Base is a repository of guides for games on ChiGame, intended to provide rules, tutorials, strategies, and other Wiki-like features. One of the main stylistic choices we emphasized was differentiating this feature from the forum. Fundamentally, the Knowledge Base is not meant to be a feature where users can casually interact with each other; rather, there are official or site-endorsed guides that are reviewed by ChiGame staff.

This notion highlights the three main user types that interact with the Knowledge Base:

1. Viewer: Every day users (logged in or not) can browse the Knowledge Base to look at the guides and learn about their favorite games.
2. Contributor: If a logged-in user wants to contribute a guide to their favorite game, they can submit a markdown file which is sent to Knowledge Base moderators for approval. Any logged-in user can contribute, subject to moderation.
3. Moderator: Knowledge Base moderators are designated by the site admin to review incoming guides and manage existing published guides.

Guide Format

The first major step in our development process was deciding how to represent the guides as data. We envisioned an interface like JupyterLab Widget's documentation that has links, a table of contents, and rich text. Therefore, we couldn't merely store guides as plaintext. We first considered implementing an existing Wiki library, but found that they would introduce too much complexity for the functionality we desired. Instead, we decided to store our guides as Markdown (which can encode a wide range of styling) and manage the rendering and presentation ourselves. Notably, this is also the same format used on GitHub and many CMSC220 assignments.

Data Storage

Since the Knowledge Base is part of the larger ChiGame Django app, we only had to add a few additional models to store our guides and the state of submitted guides. There are three key models in our implementation:

1. The Guide model stores game guides with content, status, and metadata.
2. The ReviewFeedback model stores moderators' decisions regarding guides, specifically whether they are accepted, rejected, or have changes requested (similar to feedback in a GitHub pull request).
3. The GeneralFeedback model stores feedback submitted by users on the functionality of the Knowledge Base (akin to a company's "suggestion box").

We extended the existing Game model to include a published_guide_id field to track which guide is published. We also added a moderator boolean field to the User model. We recommend that you use our fixture, which includes fairly robust test data for the Knowledge Base. You can read the instructions for how to install the fixture locally and the contents of the fixture in src/chigame/knowledge_base/fixtures/README.md.

High-level Interfaces

There are three main interaction flows with our feature that include a number of different pages. Rather than describe specific files, we will describe how a user walks through sequences of pages. Quoted phrases are intended to identify specific pages.

A normal user browsing the Knowledge Base starts on the "landing page." This presents a list of published game guides, a search bar for finding specific guides, and links to log in and contribute a guide.

Once a user has contributed a guide, they are now a "contributor" and can "manage their guides." This presents as a list of previously-submitted guides, the current status, and a link to view feedback from moderators. They can also resubmit if a guide is in "request change" status.

Finally, moderators are given their own custom views to manage published and pending guides. From the landing page, they can access the moderator dashboard which displays a list of pending guides. They can also access a second management view containing a list of games with accepted guides. This page allows them to change which guide is published and therefore displayed to users for any game.

Markdown Parsing System

We were particularly interested in how to convert Markdown text into something that can be rendered within Django. We began implementing a parser in the sandbox before transitioning the functionality into the Knowledge Base subapp. We debated using an external Wiki library, but we ultimately built our own implementation by extending an existing Markdown parser to prevent code injection (removing HTML tags and JS code contained within a Markdown submission) and external links. It supports formatting such as italics, bold text, and codeblocks (with 3 backticks). We included CSS examples in src/static/css/knowledge-base/markdown.css that demonstrate how to add additional styles. There are also other sandbox-supported features that haven't been transferred to the ChiGame parser yet:

• The Game Link Extension converts game references to clickable links
• The Code Block Extension enhances code block handling with language detection
• The Table Extension improves table rendering with Bootstrap styling
• The Image Extension secures image handling with lazy loading

These additional extensions can be a great first feature for future teams to implement. In general, the main security features implemented are (1) CSS-highlighted content sanitization, (2) link validation and sanitization, (3) resource loading restrictions, and (4) cache control for sensitive content.

Notifications

As a small quality-of-life feature, we added notifications to provide real-time feedback to users. It is implemented on top of Django's message framework. We've implemented the feature across a few key areas, and we think that future work might want to consider adding this functionality to other areas of the Knowledge Base. First, contributors receive confirmation when their guides are implemented. Second, moderators receive notifications when they successfully submit a new review feedback. Both have different displays depending on review action (accepted vs. rejected).

Dependencies

Our feature's implementation relies on a number of existing libraries and functionalities, provided by ChiGame and external resources. The Knowledge Base is stable at the time of writing, so there should not be any need to debug the interactions with these dependencies.

ChiGame Dependencies

Our features relies on ChiGame's authentication system to authenticate users and track moderator status. We also reference user IDs in our contributor feedback, tracking both the contributor and reviewing moderator. Our feature references Game objects frequently, since every Guide object is defined in relation to a Game. Notably, published_guide_id field of Game object is the only place to track the publish/unpublish status of a guide.

External Dependencies

While we try to mainly use Bootstrap for styling, we often defined our own custom CSS. We also used Python-Markdown as the core of our Markdown parser, though we extended its functionality with custom extensions.

Next Steps

There are four improvements future CMSC220 Knowledge base teams can consider:

1. Render Table of Content for Guide Detail Page

   Currently, the guide detail page for each single guide lacks a "Table of Content" portion. This feature is implemented in the sandbox markdown parser, and should be integrated into the knowledge base codebase. We hope that a user can click on a section or subsection on the table of content, and jump to that guide region. Future work can start by integrating according to the sandbox feature, and then make improvements from there.

   Issues related: #1579, "Integrate Table of Content from Markdown Parser to Guide Detail Page"

2. Allow External Links in Guides

   Currently, users are simply banned from including external links in guides they submit (i.e the links simply won't redirect the user anywhere or be rendered). This issue seeks to add the ability for moderators to grant users permission for their external links to be rendered correctly. This would allow moderation of external links without opening the door to any potential bad actors injecting malicious links into uploaded guides.

   Issues related: #639, "Implement permissions for external links in game guides"

3. User Favorited guides Page

   Currently, users are able to favorite guides, but aside from slight cosmetic changes, this doesn't really do anything. This feature would add frontend and backend support for a "Favorited Guides" list or page that users could access. This would let users have easy access to the guides the use the most, and potentially keep access to guides that are no longer published officially.

   Issues related: #1572, "Create User-Favorited-Guides Page Frontend"; #1573, "Create User-Favorited-Guides Page Backend"

4. Enable Review History for a Guide

   Currently, users are able to "resubmit" a guide if it is in the "change requested" status. The content field of the Guide object will be updated, but a new ReviewFeedback object will be created after a new feedback is given after resubmitting. This process can repeat multiple times. Future task can enable the contributor of the guide and the moderator to track the history of the review feedback for one guide, including the comments and the status for each feedback update, until a guide is finally approved.

   Issues related: #1574, "Allow Viewing History of Requested Changes for an Uploaded Guide"

Besides these tasks, here are also some ideas for future consideration: implementing guide versioning, adding support for rich media in guides, adding live preview for Markdown editing, optimizing database queries for large guide collections. Feel free to try out your own ideas and continue building on the ChiGame Knowledge Base!