Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

General curriculum: Consider adding mermaid to better express topics that are suitable for diagramming #24617

Closed
2 of 4 tasks
duckpunch opened this issue Sep 5, 2022 · 9 comments
Closed
2 of 4 tasks

General curriculum: Consider adding mermaid to better express topics that are suitable for diagramming #24617

duckpunch opened this issue Sep 5, 2022 · 9 comments
Assignees
@KevinMulhern
Labels
Status: Help Wanted This issue can be assigned to other contributors

Comments

@duckpunch
Copy link

Complete the following REQUIRED checkboxes:

  • I have thoroughly read and understand The Odin Project Contributing Guide
  • The title of this issue follows the location for request: brief description of request format, e.g. NodeJS course: Add lessons on XYZ

The following checkbox is OPTIONAL:

  • I would like to be assigned this issue to work on it

1. Description of the Feature Request:

Some parts of the curriculum lend themselves to an explanation in a visualization of some sort. Consider adding Mermaid JS to support different kinds of diagrams.

2. Acceptance Criteria:

  • Curriculum Markdown supports Mermaid, perhaps implemented as follows.
~~~mermaid
flowchart LR

some-->diagram
~~~

3. Additional Information:

Github uses this for their diagrams.

flowchart LR

like-->this
Loading

It might be enough to just include a CDN link in statics like so.
@github-actions
Copy link

github-actions bot commented Oct 6, 2022

This issue is stale because it has had no activity for the last 30 days.

@github-actions github-actions bot added the Status: Stale This issue/PR has been inactive for over 30 days and will be closed if inactivity continues label Oct 6, 2022
@KevinMulhern KevinMulhern moved this to 📋 Backlog in Curriculum Mar 10, 2023
@KevinMulhern KevinMulhern moved this from 📋 Backlog to 🆕 Needs Review in Curriculum Mar 10, 2023
@KevinMulhern
Copy link
Member

Which parts of the curriculum do you think would benefit from this @duckpunch?

@KevinMulhern KevinMulhern self-assigned this Mar 21, 2023
@KevinMulhern KevinMulhern moved this from 🆕 Needs Review to 👀 In progress / review in Curriculum Mar 21, 2023
@github-actions github-actions bot removed the Status: Stale This issue/PR has been inactive for over 30 days and will be closed if inactivity continues label Mar 22, 2023
@duckpunch
Copy link
Author

@KevinMulhern I think there can be a few places. Here are some examples. I'm sure there are probably more.

@KevinMulhern
Copy link
Member

Thank you for that breakdown @duckpunch 💪 I can see the value in it too.

To at least get things started, something like that git graph would be great in the git branches section of this lesson.

Does anybody want to take a stab at it?

@KevinMulhern KevinMulhern added the Status: Help Wanted This issue can be assigned to other contributors label Mar 24, 2023
@JoshDevHub
Copy link
Contributor

JoshDevHub commented Mar 29, 2023 •
edited
Loading

I think this is a cool idea! I played around with it some and got it working locally in the Lesson Preview tool:

image

I did have to add the mermaid node package for this as I couldn't get the CDN to work and there don't seem to be any clean integrations with Kramdown or anything (at least that I could find, definitely welcome any other thoughts on this). I feel like there might be a few concerns to get through before going all out, with probably the main one being color theme stuff, as I'm sure you want to keep things consistent with the Odin brand and/or Prism styles.

@KevinMulhern
Copy link
Member

Thanks for digging into it @JoshDevHub 💪
I would need to see it mixed with content to say for sure, but that looks really nice. Most of that coloring looks pretty good. It would be nice to have the on brand gold in place of the pink. But that wouldn't be a deal breaker for me.

For integration with Kramdown, if we need to, we may be able to write an extension similar to what Gitlab have done. We've done a little bit of that for converting lesson content.

@JoshDevHub
Copy link
Contributor

Okay I have it working locally among lesson content @KevinMulhern

Here's dark mode:
image

And light:
image

I'm just using mermaid's default dark mode here, and I actually think it looks pretty nice for both themes as is lol. Or at least this particular git diagram does. Maybe good to see how all the relevant diagram types will look.

@KevinMulhern
Copy link
Member

KevinMulhern commented Mar 29, 2023 •
edited
Loading

Thats honestly pretty amazing, it's not often these tools look that seamless out of the box lol. If you think it's worth adding to the site, I'm totally game too.

@JoshDevHub JoshDevHub mentioned this issue Mar 30, 2023
Merged
7 tasks
KevinMulhern pushed a commit to TheOdinProject/theodinproject that referenced this issue Apr 3, 2023
@JoshDevHub
Feature: Add support for mermaid diagramming (#3708)
09a163b 
<!-- Thank you for taking the time to contribute to The Odin Project. In
order to get this pull request (PR) merged in a reasonable amount of
time, you must complete this entire template. -->

## Because
<!-- Summarize the purpose or reasons for this PR, e.g. what problem it
solves or what benefit it provides. -->
[Mermaid](https://mermaid.js.org/) is a popular tool to embed diagrams
in a webpage. It's even supported here in GitHub:
```mermaid
---
title: Example Git diagram
---
gitGraph
   commit
   commit
   branch develop
   checkout develop
   commit
   commit
   checkout main
   merge develop
   commit
   commit
```
Per this
[Issue](TheOdinProject/curriculum#24617) on
the curriculum repo, I thought it would be nice to support this feature
on Odin. The above chart can be used to demonstrate git branching
concepts. They also have [class
diagrams](https://mermaid.js.org/syntax/classDiagram.html), [entity
relationship
diagrams](https://mermaid.js.org/syntax/entityRelationshipDiagram.html),
[sequence diagrams](https://mermaid.js.org/syntax/sequenceDiagram.html),
and more. I feel these visual tools can give maintainers and
contributors more options when explaining a concept in the lessons.

## This PR
<!-- A bullet point list of one or more items describing the specific
changes. -->
- Adds `mermaid` as a JavaScript dependency
- Runs `mermaid.initialize()` in `app/javascript/application.js` to get
the proper rendering of mermaid diagram sections within Lessons'
rendered HTML.
- Runs the asynchronous `mermaid.run()` in the `LessonPreview` react
component in order to provide mermaid rendering in the Lesson previews.

## Issue
<!--
If this PR closes an open issue in this repo, replace the XXXXX below
with the issue number, e.g. Closes #2013.

If this PR closes an open issue in another TOP repo, replace the #XXXXX
with the URL of the issue, e.g. Closes
https://github.com/TheOdinProject/curriculum/issues/XXXXX

If this PR does not close, but is related to another issue or PR, you
can link it as above without the 'Closes' keyword, e.g. 'Related to
#2013'.
-->
Closes #XXXXX

## Additional Information
<!-- Any other information about this PR, such as a link to a Discord
discussion. -->
#### How to Use
The Lesson Preview is probably the easiest way to try it out. Visit the
[mermaid docs](https://mermaid.js.org/intro/) to learn the syntax of
different diagram types. Then you can visit Lesson Preview and try:
```md
<pre class="mermaid">
  <mermaid_code>
</pre>
```
You can also see it on an actual Lesson page by altering the body
content of a lesson, just be sure to surround the added content in
`<pre>` tags with a `class="mermaid"`, as that is specifically what
`mermaid` is looking for. There are ways to alter which element(s) it
targets ([docs on
that](https://mermaid.js.org/config/usage.html#using-mermaid-run)), and
I'm certainly interested if there's anything people think would be
better than the default regarding that.
#### Color Theme
I just stuck with mermaid's provided dark theme as I think it looks
pretty good with Odin's light and dark modes. Here are a couple of
screenshots of what the example git diagram looks like in a lesson
context:

Dark mode:

![228610360-1834a800-6c6d-425c-81f5-8935f387792a](https://user-images.githubusercontent.com/88392688/228725382-45e37eaf-b360-44b5-b16b-d6e904fbdb70.png)

Light mode:

![228610940-e9ec8ed6-5baa-4d04-a4d5-5e4d5901143f](https://user-images.githubusercontent.com/88392688/228725410-ea7ffa31-1330-4731-b1a9-921b2f3e5545.png)


Definitely willing to accept other ideas on this. They do have a
[system](https://mermaid.js.org/config/theming.html#customizing-themes-with-themevariables)
in place for making custom themes.

## Pull Request Requirements
<!-- Replace the whitespace between the square brackets with an 'x',
e.g. [x]. After you create the PR, they will become checkboxes that you
can click on. -->
- [x] I have thoroughly read and understand [The Odin Project
Contributing
Guide](https://github.com/TheOdinProject/theodinproject/blob/main/CONTRIBUTING.md)
- [x] The title of this PR follows the `keyword: brief description of
change` format, using one of the following keywords:
  - `Feature` - adds new or amends existing user-facing behavior
- `Chore` - changes that have no user-facing value, refactors,
dependency bumps, etc
  - `Fix` - bug fixes
-   [x] The `Because` section summarizes the reason for this PR
- [x] The `This PR` section has a bullet point list describing the
changes in this PR
- [x] I have verified all tests and linters pass after making these
changes.
- [x] If this PR addresses an open issue, it is linked in the `Issue`
section
-   [x] If applicable, this PR includes new or updated automated tests
@JoshDevHub JoshDevHub mentioned this issue Apr 16, 2023
Merged
7 tasks
@KevinMulhern
Copy link
Member

Happy to close this one off now. We've got mermaid on the site, in the docs and the first diagram has been added to the lesson content. All thanks to @JoshDevHub.

Thanks @duckpunch for opening this issue, it was a great idea.

If there are any further ideas of where we can use diagrams in the curriculum. Please feel free to open issues for them.

@github-project-automation github-project-automation bot moved this from 👀 In progress / review to ✅ Done in Curriculum Apr 19, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@KevinMulhern KevinMulhern

Labels
Status: Help Wanted This issue can be assigned to other contributors
Projects
No open projects
Curriculum
Archived in project
Milestone
No milestone
Development

No branches or pull requests
3 participants
@duckpunch @KevinMulhern @JoshDevHub