Adds `mermaid.js` and `highlight.js` for code formatting along with `Fire` managed args to mkposter #4

stanbiryukov · 2022-04-27T18:07:44Z

Adds:

mermaid.js diagram support for rendering mermaid blocks
code rendering with highlight.js, default github theme
pass arguments to mkposter using Fire
- adds background_color str argument with default #FFFFFF
- adds code_style str arg for highlight.js themes with default 'github'
- adds port int arg to specify http.server port, with 8000 as default.

Example:

python -m mkposters "research_app/poster" --code_style "github" --background_color "#F6F6EF" --port 8000

Sb design

Adds `mermaid` and github theme `highlight.js` for code formatting along with `Fire` managed args to mkposter

flake8 docstring fix

use `highlightAll()`

patrick-kidger

This looks great.

patrick-kidger · 2022-04-28T07:23:57Z

mkposters/mkposter.py

@@ -42,8 +70,15 @@ def mkposter(datadir):
        html_out = rf"""<!doctype html>
        <html>
        <head>
+        <body style="background-color:{background_color}">


This isn't well-formed HTML: you've added an open body tag in the middle of the head.

Personally I subscribe to the "do all styling through CSS" approach, and to never use inline styles.

Perhaps the best thing to do here would be to allow for user-specified SCSS (alongside the markdown). And then let the background color just be set there if desired.

Good point on user specified SCSS. I started editing the custom.scss first and wanted to generalize at minimum the background color so added some non-ideal html. I agree adding a custom option for a user file is the right approach. I can work on that in this PR.

Addressed in most recent push as scss optional user specified path.

patrick-kidger · 2022-04-28T07:32:00Z

mkposters/mkposter.py

        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700%7CRoboto+Mono&amp;display=fallback">
        <link rel="stylesheet" type="text/css" href="style.css"/>
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/{code_style}.min.css">
+        <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/highlight.min.js"></script>
+        <script>hljs.highlightAll();</script>


Can these two lines be optional (based on a particular magic value of code_style) and bump the minor version number (as this is backward-incompatible).

Sure good point. On some browsers the superfences just wasn't working so added the highlight.js which seemed to do the trick.

To future proof a bit more, what are your thoughts on working towards something like a user specified mkposters.yml to mirror mkdocs.yml design? That way we can add additional markdown extensions, and user specified scss. That said, it would significantly expand the scope of work, which I likely won't have bandwidth for, and may not be entirely useful if the target audience is researchers who just want easily create one page posters with pure markdown without caring about managing yaml and any other settings outside of markdown. I wonder if you have a vision for the API/goals of the project to help guide the development decisions for some of these types of custom additions?

Right, different browsers have pretty different behaviour. There's a reason I mandated specifically Firefox in the README, as nothing else seemed to work reliably.

As for having a mkposters.yaml. I'd definitely be open to this, but likewise don't plan to implement this myself. MkPosters is just an afternoon project I created to avoid any more wrestling with LaTeX when making my own academic posters, and the default style is just the one I personally use for all my posters.

So MkPosters isn't a project I plan to offer "official" support for (unlike some of my other work), and I don't have any real vision/goals for this project. But if this is a tool that's useful to other people then I'm very happy to continue accepting any PRs from folks who find it useful enough to tweak it to their needs.

Great, that was my impression as well. I honestly would prefer to avoid starting down the yaml path and would rather keep it as simple as possible from a user experience perspective. I like the idea of an optional user specified scss, which I can bundle in this PR.

Thanks again for sharing this work - I've demoed an internal project using the html rendered with mkposters and find it useful for quickly creating a poster style presentation given my rusty html. I've also shared the torchsde -> diffrax work in a couple internal Lunch 'n Learns which, along with your thesis, are awesome.

Made code style and mermaid optional for backwards compatibility in latest commit.

…, mermaid support, and highlight.js code style

Sb mermaid

patrick-kidger · 2022-04-30T17:29:57Z

mkposters/mkposter.py

+def mkposter(
+    datadir: str,
+    code_style: Optional[str] = None,
+    mermaid: Optional[bool] = False,


I don't think is Optional, just bool.

The goal with the optional type and default of None was to preserve backwards compatibility. Or do you suggest we move forward with these as required args, with no default values, and then bump the minor version?

Sorry, I'm talking about the mermaid argument here, not the code_style argument. I just mean the existing behaviour is already mermaid=False, and passing mermaid=None does nothing.

patrick-kidger · 2022-04-30T17:30:07Z

mkposters/mkposter.py

+    code_style: Optional[str] = None,
+    mermaid: Optional[bool] = False,
+    scss: Optional[Union[str, pathlib.Path]] = None,
+    port: Optional[int] = 8000,


Likewise not Optional, just int.

(Likewise passing port=None here isn't meaningful.)

mkposters/mkposter.py

patrick-kidger · 2022-04-30T17:33:38Z

mkposters/mkposter.py

@@ -68,10 +121,14 @@ def mkposter(datadir):
        if not (_here / "third_party" / "dart-sass" / "SASSBUILT.txt").exists():
            post_install(package_dir=str(_here))

+        style_sheet = f"{_here}/style.scss"
+        if scss:
+            style_sheet = scss


I think it'd be better to look inside datadir for style.scss, just like how we currently look for poster.md.

Do you think it'd be better to have custom styling completely override the default styling (as is the case at the moment) or just override it?

Good point - we can look for style.css in datadir. That also requires all referenced imports to be in the datadir. I was thinking if the user specifies a style sheet it would enable them to have a new custom.scss and provide flexibility to change import logic that may or may not use the third_party icons and stylesheets.

Worth noting that the current implementation will just override/ignore any existing user-specified file.

I think the best overall behaviour here would be to check if the user has a style.scss file inside datadir, and to have an additional override_scss flag passed to mkposter, defaulting to False. If override_scss==False then the user-specified style.scss is appended to the default style.scss prior to running dart-sass. If override_scss=True then the user-specified style.scss is used instead of the default style.scss when running dart-sass.

addressing comments Co-authored-by: Patrick Kidger <[email protected]>

…ir`, similar to how `poster.md` is looked for.

stanbiryukov and others added 14 commits April 26, 2022 21:02

highlight.js github theme for code syntax

4f5e74c

warmer background

1b8c458

code_style source; fix href

bf9792f

Merge pull request #1 from stanbiryukov/sb_design

a08f00b

Sb design

add mermaid support

61864fa

use fire to manage args to mkposter

ba43196

add background_color as arg

26cca3b

add port as arg; #FFFFFF as default background.

129fc30

add example to docstring

983b8e3

Merge pull request #2 from stanbiryukov/sb_mermaid

fb82ad8

Adds `mermaid` and github theme `highlight.js` for code formatting along with `Fire` managed args to mkposter

flake8 docstring fix

73e868f

Merge pull request #3 from stanbiryukov/sb_mermaid

34b3d30

flake8 docstring fix

use highlightAll()

98d0afc

Merge pull request #4 from stanbiryukov/sb_mermaid

522858c

use `highlightAll()`

patrick-kidger reviewed Apr 28, 2022

View reviewed changes

stanbiryukov and others added 4 commits April 28, 2022 15:52

Merge branch 'patrick-kidger:main' into sb_mermaid

fab7b10

drop html version of background color in favor of custom css

294ef83

addresses comments; optional args for user specified scss style sheet…

19724f6

…, mermaid support, and highlight.js code style

Merge pull request #5 from stanbiryukov/sb_mermaid

ebe1d55

Sb mermaid

stanbiryukov requested a review from patrick-kidger April 29, 2022 18:07

patrick-kidger reviewed Apr 30, 2022

View reviewed changes

stanbiryukov and others added 2 commits May 12, 2022 09:49

Update mkposters/mkposter.py

578cc1a

addressing comments Co-authored-by: Patrick Kidger <[email protected]>

address comments: preserve reference to a main style.scss in `datad…

0bae1d6

…ir`, similar to how `poster.md` is looked for.

stanbiryukov requested a review from patrick-kidger May 12, 2022 15:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds `mermaid.js` and `highlight.js` for code formatting along with `Fire` managed args to mkposter #4

Adds `mermaid.js` and `highlight.js` for code formatting along with `Fire` managed args to mkposter #4

stanbiryukov commented Apr 27, 2022

patrick-kidger left a comment

patrick-kidger Apr 28, 2022

stanbiryukov Apr 28, 2022

stanbiryukov Apr 29, 2022

patrick-kidger Apr 28, 2022

stanbiryukov Apr 28, 2022

stanbiryukov Apr 28, 2022

patrick-kidger Apr 28, 2022

patrick-kidger Apr 28, 2022

stanbiryukov Apr 28, 2022

stanbiryukov Apr 29, 2022

patrick-kidger Apr 30, 2022

stanbiryukov May 12, 2022

patrick-kidger May 13, 2022

patrick-kidger Apr 30, 2022

patrick-kidger May 13, 2022

patrick-kidger Apr 30, 2022

stanbiryukov May 12, 2022

patrick-kidger May 13, 2022

Adds mermaid.js and highlight.js for code formatting along with Fire managed args to mkposter #4

Are you sure you want to change the base?

Adds mermaid.js and highlight.js for code formatting along with Fire managed args to mkposter #4

Conversation

stanbiryukov commented Apr 27, 2022

patrick-kidger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Adds `mermaid.js` and `highlight.js` for code formatting along with `Fire` managed args to mkposter #4

Adds `mermaid.js` and `highlight.js` for code formatting along with `Fire` managed args to mkposter #4