Skip to content

HTML: add elk layout engine as option for HTML display #2526

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.

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

Open
wants to merge 5 commits into
base: master
Choose a base branch
from

Conversation

@ascholerChemeketa ascholerChemeketa force-pushed the mermaid-add-elk-render-engine branch from c343e87 to 1a27d12 Compare May 22, 2025 00:24
@rbeezer
Copy link
Collaborator

rbeezer commented May 27, 2025

Small follow-up from Drop-In. It'd be great to have an example of how you specify this for the sample article, perhaps the one used in the demos above.

@ascholerChemeketa
Copy link
Contributor Author

We do have an existing pub var for @theme. I am ready to go with adding @layout-engine for book level config.

They both get rendered down (all use cases) toJS - either a JSON file or JS that is written into the HTML output.

And there are other options someone might want to play with. So at this point I am wondering do we just provide a way to put JSON in the pub file (publisher/common/mermaid would be an element that has json)? Or to point to a JSON file to use? Feels better than getting into the business of creating markup for every Mermaid option someone might want to specify at the book level.

@ascholerChemeketa
Copy link
Contributor Author

It would be easy enough to deprecate the @theme on publisher/common/mermaid but rewrite it into the correct JSON inside the element.

More complex to fix up via writing to an external file, but also doable.

@rbeezer
Copy link
Collaborator

rbeezer commented May 28, 2025

OK, you've lost me on this one. ;-) I thought this was complete, but then there could be a new mermaid image that would utilize this newly-available layout. Like the Mermaid code would say "use elk layout" somewhere early on. But I guess I don't understand something.

And, BTW, the idea of JSON in the publisher file gave me a real shock.

@ascholerChemeketa
Copy link
Contributor Author

Force pushed with awful commit so you can see what I was blathering about.

In drop in you had started to muse about a book level default for renderer if we already were doing something else in the pub file for mermaid. At the time I said "no, we don't have a pub var" - had forgotten about theme.

Rather than create pub attributes on mermaid 1 by 1 (and then try to keep them in sync with anything that happens in mermaid land), I am thinking it would be better to let author's point to some JSON that has the configs they want.

Or we call it good enough for now and if there is ever a demand for a third config option we think about refactoring. In which case I can rebase to clean up commits and we should be done.

@ascholerChemeketa
Copy link
Contributor Author

Case in point... I am realizing I would love to have "hide empty member boxes in class diagrams" default to on.

Hypothetically, someone might want to specify this set of options for the base initialization:

{
  "theme": "forest",
  "layout": "degree",
  "look": "handDrawn",
  "gitGraph": {
     "mainBranchName": "master",
     "showCommitLabel": false,
  },
  "class": {
     "hideEmptyMembersBox": true,
     "layout": "elk",
  },
}

So I am thinking let them put that in a file and have pub var specify name of the file. Instead of creating pub file markup so they can specify every possible option.

@rbeezer
Copy link
Collaborator

rbeezer commented Jul 14, 2025

Hypothetically, someone might want to specify this set of options for the base initialization:

Who is the "someone"? ;-)

That sounds to me like something an author would set, like our various *-preamble" elements in docinfo`.

Re-theme-ing should be a publisher option. Change the look, not the content. A layout engine does feel like it might be a publisher choice.

Maybe an empty box is important, how does the publisher know? Most important branch of my git repo is master or is main? Surely I have narrative referencing one or the other, and that is an author's decision. (Says an author who would someday like to use this for their "how to do git" pamphlet.)

Let's give the author source/preamble/initialization freedom/setup and let's constrain the publisher to what they can legitimately mess around with.

Do layout here as a publisher option? New PR for a docinfo/mermaid-preamble?

@ascholerChemeketa
Copy link
Contributor Author

Publisher for layout engine & theme makes sense. Which is what we have right now. I'll clean it up and force push.

Mermaid preamble for author stuff will go on the "someday" list.

@ascholerChemeketa ascholerChemeketa force-pushed the mermaid-add-elk-render-engine branch from 7917524 to 656e5ba Compare July 14, 2025 19:33
@ascholerChemeketa ascholerChemeketa force-pushed the mermaid-add-elk-render-engine branch from 656e5ba to b868048 Compare July 14, 2025 19:59
@ascholerChemeketa
Copy link
Contributor Author

Just tested in HTML and PDF. Looks good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants