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

docs: Render mermaid graphs #568

Merged
merged 6 commits into from
Apr 9, 2024
Merged

docs: Render mermaid graphs #568

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
2da9f71
add mermaid2 plugin
lewismiddleton Apr 3, 2024
8a06255
trunk fmt
lewismiddleton Apr 3, 2024
be47904
Merge branch 'main' into mermaid-plugin
lewismiddleton Apr 3, 2024
4cf0a1b
Revert "add mermaid2 plugin"
lewismiddleton Apr 8, 2024
868e310
superfences fence_code_format
lewismiddleton Apr 8, 2024
4bbc5a9
Merge branch 'main' into mermaid-plugin
tcarmet Apr 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,9 @@ nav:
- Testing: development/testing.md
- Workflows: development/workflows.md

plugins:
- mermaid2

markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
Expand All @@ -56,7 +59,11 @@ markdown_extensions:
emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.inlinehilite
- pymdownx.snippets
- pymdownx.superfences
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid_custom
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey @lewismiddleton! Thanks for your contribution and for spotting this issue, very much appreciated!

In my other mkdocs project I did the following:

Suggested change
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:mermaid2.fence_mermaid_custom
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format

For me it seems like a healthier change as it doesn't require the extra dependency to be installed, would you mind giving it a shot see if it renders as you would like compared with mermaid2.

Thanks in advance!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I agree, a better solution if it works. I wasn't able to get that working, give it a try on your environment and see what you think?

You're right though in that the docs say it should be sufficient. I'm curious to know what the difference is between this project and others (if there is actually an issue - idk maybe my environment is just differnet)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did try it and it worked.

Worth mentioning though that I was running my doc website through a mkdocs serve and reaching it on localhost:8000 through my browser and not via the mkdocs build, it seems like you were using the build method and I don't know if that may cause some differences in the rendering.

Regardless I have another website with those options hosted on GitHub pages that is working fine as well for rendering the mermaid graphs.

Let's give it a go with only the suggestion above, merge the PR, then if it's doesn't work we'll review the addition of the plugin.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah I was using poetry run mkdocs build --strict but can confirm mkdocs serve works on my machine too.

I've reverted the commits and pushed the suggested change.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome! Thank you for your patience and making the suggested changes ❤️

And good to know it doesn't behave the same with a mkdocs build!

- tables
- attr_list
- md_in_html
Expand Down
80 changes: 79 additions & 1 deletion poetry.lock
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ optional = true
[tool.poetry.group.docs.dependencies]
mkdocs-material = "^9.5.15"
mkdocs = "^1.5.3"
mkdocs-mermaid2-plugin = "^1.1.1"

[tool.poetry.group.dev.dependencies]
connexion = "^3.0.5"
Expand Down
Loading