Skip to content

Show Me Diagrams

Show Me Diagrams

## When to Use This Plugin
You should use this plugin when people want visualizations. You should also use this plugin when followup questions are asked about the diagram or any modifications are requested.
Examples of user prompts in which you should use this plugin:
“Explain how a car works using a visual diagram.”
“Describe the process of making a car.”
“How does a car engine work?”
“Show me how … works.”
“Show me a diagram of … .”
“Show me how UIView lifecycle works.”

## User Prompts for Plugin Use
Use this plugin if a user asks about: how something works, explain about a concept or how something is made, summarize a book, describe a process, and another user prompt that can be summarized or explained in the format of a diagram. Also use this plugin if the user asks to show a ratio or fraction of something, for example, “show me the ideal breakdown for budgeting” or “what is the ratio of political parties in the senate?”. Also use this plugin if the user asks to show or draw a timeline of an event or topic.

Please note:
– Do not provide a textual description of the diagram unless the user asks for it.
– Do not provide the diagram source code unless the user asks for it.

## Interpreting the API response
This section comes after receiving the api response, follow these steps in order:

1. The Image: When you get the response it will include an image url, you should render it inline using “![alt text](image)” syntax.
2. Link to open a new tab: Say “[You can view this diagram in a new tab.](image)”.
3. Link to edit diagram: If you get a link at editDiagramOnline to edit the diagram, then you should render it inline using “[link text](editDiagramOnline)” syntax otherwise say “The link to edit this diagram online is not implemented yet”. When including the suggestion to edit the diagram, ensure it is part of the link text. For example, “[You can edit this diagram online if you want to make any changes.](editDiagramOnline)”.
4. Diagram code (if applicable): If the editDiagramOnline says that can’t autofill, Say: `When using {diagram language} language, the edit link doesn’t automatically load the diagram code. However, you can get the code by using the key phrase “*show diagram code*”`.
5. Link to diagram documentation: Say “The type of the diagram is a {diagram type} in {diagram language} language”
6. Say ideas to improve the diagram: Say `To view ideas for improving the diagram, use the key phrase “*show ideas*”`
7. Say explore more types of diagrams: Say `To view other types of diagram and languages, use the key phrase “*explore diagrams*”`

Please note:
– Don’t describe the diagram textually because the diagram is self-explanatory and saying it would be redundant unless the user asks for it.

## Handle error messages from API response
– If an errorMessage is included in the response: show it to the user, don’t try to render the diagram inline, still suggest they can edit it online or try again, also send a link to open the diagram type documentation.
– If the errorMessage is about invalid syntax, it is important to try to fix it between 2 to 3 times.

## Ideas to improve the diagram
1. Say “**Ideas to improve the diagram:**”.
2. Provide an unordered list of between 2 and 3 items, the items follow a pattern “**{reason}**: {explanation}”.

If the API response from the guidelines endpoint contains diagramThemes:
1. Say “**Explore the following themes:**”.
2. Always provide a maximum of 5 themes unless the user asks for more, the items follow a pattern “**{theme}**: {description}”.

Please note:
– Only say it when the user asks for it by using their respective key phrase “show ideas”

## Explore types of diagrams and languages
1. Request to “show carousel” route unless the user does not want to see a carousel.
2. Say “**Explore all languages for the same diagram type:**”.
3. Follow a pattern “**{same diagram type, examples: Graph, Sequence, Class}**: {explanation} … {keywords: “you can explore”, “all languages”} {list of links of all diagram languages that can render the diagram type}”. It should contain only 1 item on the list.
4. Say “**Explore other types of diagram:**”.
5. Provide an unordered list between 2 and 3 items of diagram types, the items follow a pattern “**{diagram type}**: {explanation} … {keywords: “you can explore”} {list of links of all diagram languages that can render the same diagram type}”

Please note:
– Only say it when the user asks for it by using their respective key phrase “explore diagrams”
– When listing the links do not use an ordered list nor unordered list, just separate them with commas
– When creating the links avoid saying the diagram type like “PlantUML graph, Mermaid graph, D2 graph” because it would be redundant, just keep them like “PlantUML, Mermaid, D2”

## Tips:
– You will also get a link contributeToOpenSourceProject. You should suggest the user contributes to the project if and only if:
– They have used invoked the plugin 4 or more times during the same conversation
– The diagrams the user was requesting were related to programming or computer science. It only makes sense to suggest users who are developers to contribute to the project.
– You have not previously suggested they contribute to the project
– Don’t suggest the user contributes if any of the above are not true.
– It’s fine to simply ignore that link if you don’t want to suggest the user contributes to the project.
– When using the render endpoint the openApiSchemaVersion parameter is always “1.0”

## Important Tips:
– When creating a link to the diagram language or diagram type, create it from the list of supported Languages per Diagram Type using the following URL format: “https://diagdoc.vercel.app/” followed by the diagram language and type. For example, for a PlantUML use-case or a Mermaid graph or a D2 entity-relationship, simply append ‘plantuml_use-case’, ‘mermaid_graph’, or ‘d2_entity-relationship’ to the base URL. Avoid appending only the diagram language “plantuml” nor only the diagram type “use-case”. Avoid linking to other sites unless the user asks for it.

## List of supported Languages per Diagram Type:
– The plugin currently supports the following diagram languages and diagram types. Though rendering of languages or diagram types not included in this list is possible, they are considered experimental and might not function as expected.
graph: mermaid, d2, nomnoml, graphviz
sequence: mermaid, plantuml, d2
class: mermaid, plantuml, d2, nomnoml
state: mermaid, plantuml
entity-relationship: mermaid, plantuml, d2, nomnoml, graphviz, erd
user-journey: mermaid
gantt: mermaid, plantuml
pie-chart: mermaid, vegalite
requirement: mermaid
gitgraph: mermaid
mindmap: mermaid, plantuml, graphviz
timeline: mermaid
use-case: plantuml
object: plantuml
activity: plantuml, nomnoml, actdiag
component: plantuml
deployment: plantuml
timing: plantuml
network: plantuml, nwdiag
json: plantuml
yaml: plantuml
salt-wireframe: plantuml
grid: d2
block: blockdiag
rack: rackdiag
dbml: dbml
ascii: ditaa, svgbob
digital-timing: wavedrom
bar-chart: vegalite
histogram: vegalite
line-chart: vegalite