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

[CT-1452] Support mermaid in markdown #338

Closed
il-dat opened this issue Nov 1, 2022 · 4 comments · May be fixed by #375
Closed

[CT-1452] Support mermaid in markdown #338

il-dat opened this issue Nov 1, 2022 · 4 comments · May be fixed by #375
Labels
enhancement New feature or request help_wanted Trickier changes, with a clear starting point, good for previous/experienced contributors Stale triage

Comments

@il-dat
Copy link

il-dat commented Nov 1, 2022

Describe the feature

I have seen many places where mermaid can rich the documentation very well.
That's why I've tried to utilize it within dbt project, but it doesn't work yet.

Additional context

  • dbt model doc
  • dbt macro doc
  • general doc

Who will this benefit?

  • dbt docs site will become richer with mermaid diagrams
  • open the door for programmatically generating the diagrams/flows within md files, even use it for building ERD
    Sample mermaid for ERD:
erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string name
        string custNumber
        string sector
    }
    ORDER ||--|{ LINE-ITEM : contains
    ORDER {
        int orderNumber
        string deliveryAddress
    }
    LINE-ITEM {
        string productCode
        int quantity
        float pricePerUnit
    }
@il-dat il-dat added enhancement New feature or request triage labels Nov 1, 2022
@github-actions github-actions bot changed the title Support mermaid in markdown [CT-1452] Support mermaid in markdown Nov 1, 2022
@jtcohen6
Copy link
Contributor

jtcohen6 commented Nov 17, 2022 •
edited
Loading

Agree that this would be cool! It's unlikely something that we'll be prioritizing ourselves in the near future, given our ongoing commitment to dbt-docs right now can only be parity + stability. But perhaps as a hackathon project for someone interested??

dbt-docs is still written in Angular (!). After a quick search, it looks like there are some resources online for how to integrate the two. Ideal UX here would be the ability to add code blocks with ```mermaid, just like in GitHub Markdown.

We'd need to ensure that this is copacetic from a security standpoint. It looks like there have been some issues in the past (https://security.snyk.io/vuln/SNYK-JS-MERMAID-174698), but also that the team behind mermaid is serious about resolving these.

I've also heard some votes in favor of https://github.com/plantuml/plantuml, as a preferable text-to-visual framework for graphs. It sounds like Mermaid might be easier to write, but PlantUML has been around longer, it's more feature-rich, and it has fewer limitations around the edges.

I'm going to call this help_wanted, if anyone wants to give it a spin!

@jtcohen6 jtcohen6 added help_wanted Trickier changes, with a clear starting point, good for previous/experienced contributors and removed triage labels Nov 17, 2022
@dbeatty10 dbeatty10 mentioned this issue Feb 20, 2023
Open
@matthieucan matthieucan mentioned this issue Feb 22, 2023
Open
5 tasks
@github-actions GitHub Actions
Copy link
Contributor

This issue has been marked as Stale because it has been open for 180 days with no activity. If you would like the issue to remain open, please comment on the issue or else it will be closed in 7 days.

@github-actions github-actions bot added the Stale label Nov 13, 2023
@github-actions GitHub Actions
Copy link
Contributor

Although we are closing this issue as stale, it's not gone forever. Issues can be reopened if there is renewed community interest. Just add a comment to notify the maintainers.

@github-actions github-actions bot closed this as not planned Won't fix, can't repro, duplicate, stale Nov 20, 2023
@matthieucan
Copy link

I believe this should be reopened, there is a PR adding mermaid.js support for which maintainers' attention would be really appreciated

@datnguye datnguye mentioned this issue Apr 25, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request help_wanted Trickier changes, with a clear starting point, good for previous/experienced contributors Stale triage
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Integrate mermaid.js to render graphs in markdown matthieucan/dbt-docs
3 participants
@matthieucan @jtcohen6 @il-dat