Content Management Proposal

Introduction

During 2021, in addition to the visualiser, we had discussed the usefulness of integrating learning resources specifically created for COMP1511/COMP2521/COMP**** such as:

• Articles (written in a wiki-like style, or even as an informal blog like what you’d find on Medium – example).

• Quizzes.

• Code snippets as a quick reference (although the usefulness of this should be discussed further).

• YouTube videos.

• Flashcards (this wasn’t ever discussed in 2021, however this would be an interesting concept to explore – I was inspired from reading this very insightful article around learning mediums that maximise memory retention).

A few other motivations for introducing these integrated learning resources include:

• It may help expand the scope of the project to allow for greater community contributions.

• The content is likely to be evergreen and will continue to benefit UNSW CSE students for years after 2022.

• Having content alongside the visualiser could really improve search engine discoverability and attract more organic traffic from a wider audience than just UNSW students.

How to Implement

The current setup is problematic because:

• It brings in a relational data model and database when we don’t really need one. A database really only makes sense if we have a lot of structured data that needs to obey constraints, and/or if the data is very dynamic (ie. we are regularly inserting, updating, deleting).

• The current setup is unnecessarily complex/bloated. We don’t need a backend and we shouldn’t have to build our own admin page to manage content. We literally just need a filesystem as our ‘database’. This is how it’s done for the vast majority of sites that have static-but-changing content (think GeeksForGeeks, WikiPedia, etc.).

• It was rushed.

A better setup this doc proposes involves:

• Using MDX, which is a superset of Markdown that supports custom React components (and which can be very easily extended to support LaTeX).

  • Why? We’d very likely want the content to include some complex React components (eg. a multiple-choice question, an embedded video, an animation, etc.) which would not be possible to include when using regular Markdown.
    The expressive power of MDX would let us create interactive articles, which would be a significant edge over the ‘competition’ like GeeksForGeeks. Impressive demo of what’s possible with MDX.

  • We would use an MDX bundler like this one to get the MDX file’s contents to be displayed on our visualiser controller page inside a pane (or elsewhere).

  • Caveat: the main drawback is that MDX is not very portable, but this shouldn’t matter for us since we’re not expecting to pack up the files in the future and serve them on another platform.

• Not using a database. We should just keep the content as .mdx files in a directory inside the Structs.sh repo and keep it version-controlled along with the source code.

• Adopting Next.js. Next.js makes static site generation or server-side rendering extremely simple. Both are very beneficial to SEO which would matter if we want to attract organic traffic to Structs.sh.

  • Note: migrating to Next.js should not be too challenging as it is a commonly done procedure for many production projects. See ‘Migrating from Create React App’.

All-in-all, the above approach simplifies both content creation and quality assurance. To contribute a new page of content, authors would just create a new .mdx file and go through the same pull request process.

Note: we should delete the entire backend from 2021 if we take this approach.

Concerns:

• Only developers would be able to author content. This is a reasonable assumption to make since content writers should all be developers anyway.

• If we adopt Next.js:

  • The React codebase would be disturbed and some directories/files would inevitably have to be moved around.

  • An extra obstacle for new contributors to Structs.sh. This shouldn’t be much of a concern however – you do not need to know much about Next.js or work directly with it (if at all).

  • Need to tweak deployment settings in Dockerfiles & Rancher.

Example Workflow

This is an example of how a content creator might make a new contribution to Structs.sh.

Suppose you want to write a page to introduce AVL-trees. You would:

1. Create a new file at the path: Structs.sh/content/trees/AVL-tree.mdx.

2. Write the Markdown/LaTeX/JSX source code for that page. Eg.

   import SomeComponent from 'components/SomeComponent' # AVL Trees An AVL tree is ... Insertion has time complexity $O(\log{n})$. <SomeComponent /> ... and so on.

3. Open a PR and get it merged to the production branch.

Our build process would then run the MDX bundler to convert this .mdx file into a regular React component that can be rendered wherever we’ve chosen to render it on the site.