acmucsd / acm-ai-workshops Goto Github PK

(found in #16 ) Regular markdown allows for inline html, which uses strings for passing certain properties (e.g. <font color="red">, or <span style="color: red">). However, the website parses html as JSX, which uses a different syntax.

As part of the notebook conversion step, the Markdown AST or HTML AST should probably be traversed to convert "standard" HTML elements to valid JSX, by parsing properties that differ between them e.g. color, style, and class/className

There also appears to be an issue with mdx-bundler being unable to render regular strings with a forward slash in them, such as a url.

Possible fix: mdx supports "vanilla" markdown parsing (https://github.com/mdx-js/mdx/tree/main/packages/mdx#optionsformat) which hopefully would be able to resolve all of these various issues of markdown incompatibility. However, there are two issues that still stand:

1. mdx-bundler can't seem to properly handle the files when setting the markdown format to md
2. how should the table of contents be obtained otherwise?
   • one idea I have is to do two passes when bundling - one, for the actual bundling of the markdown, and the other, which gets the table of contents by inlining the plugin and modifying a toc variable in scope to get the toc for each page. however, this will require a significant refactor

Currently, the website is not optimized for a mobile viewing experience - the navbar, sidebar, and table of contents all don't render properly on mobile. Spacing could additionally be adjusted for smaller width devices.

There should be some simple automatic syntax highlighters out there to auto highlight the python code in these jupyter notebooks

For example, at the top of this tutorial on pytorch:

https://pytorch.org/tutorials/intermediate/seq2seq_translation_tutorial.html

Which link to
https://colab.research.google.com/github/pytorch/tutorials/blob/gh-pages/_downloads/a60617788061539b5449701ae76aee56/seq2seq_translation_tutorial.ipynb

which seems automatable.

Currently, notebooks are converted into a long Markdown document, where Jupyter code cells are simply rendered as markdown code blocks. However, this means that if a markdown cell contains a code block, this code block is indistinguishable from a Jupyter code cell. There are several possible approaches to solve this issue:

1. we could simply indent markdown code blocks by a small amount. this would be the simplest solution.

2. we could modify the notebook rendering process to factor in the ideas of Jupyter "cells" - this way, we could additionally do things like adding the cell number on the left (idk what it's called, basically the execution order thing tho), or being able to collapse the output as you would in an actual Jupyter notebook.

cc @StoneT2000 what are your thoughts?

Currently, our Jupyter Notebook pages don't render any output. Ideally, we should be able to render at least plaintext output and images (i.e. matplotlib graph)

The pipeline for generating pages from Jupyter notebooks, and being able to extend it to generate pages for e.g. Markdown documents or anything else, is somewhat complex and not fully documented, making it difficult for new contributors to help. Every function should be properly documented, and an ARCHITECTURE.md or other document should be made describing how the codebase works.

• remove some of the older content that's not up to the same quality as our most recent ones.

E.g. if going to a folder, list all folders and files there etc.

Currently, the website has no code linting or style enforcement - there is a cacophonous mix of semicolons and no semicolons, single and double quotes, random order of css properties, etc. We should add a linting and styling config to standardize this.

could use format [notebook name].metadata.yml or something.
categories might just use a reserved name (to avoid naming collisions w/ its files), e.g. __category.metadata.yml or something.