Not sure how to change stylesheet

[pwright]

Asciidoctor supports using a custom stylesheet (to change how html looks) using the following;

= My First Tutorial
:stylesheet: mystyles.css

And while asciidoctor applys this stylesheet in cli, didact doesn't seem to pick up the file (@bfitzpat maybe related to 'include issue'?)

Is there an alternative 'didact' way of changing the stylesheet (perhaps for both md and adoc)?

[bfitzpat]

At this point, there is no way to change the stylesheet directly. We are using the asciidoctor css from upstream at present and that's a fixed entity that gets pulled into the generated HTML. Due to the way that the web view locks down how certain things get pulled into play (various CSS, images, etc), I'm not sure that this approach with pulling in a custom stylesheet is possible.

It's definitely something I can look into however!

[bfitzpat]

Chatted with @pwright today...

When asked for a css he might apply in this manner, he provided:

.system\:abstract {
    color: rgb(50, 33, 148);
    font-size: 200%;
  }

He suggested that it can be done using the asciidoctor browser extension (https://github.com/asciidoctor/asciidoctor-browser-extension) adding stylesheets in the "additional resources" section:

Looking further, we looked at the converter used in the browser extension: https://github.com/asciidoctor/asciidoctor-browser-extension/blob/master/app/js/converter.js

In that code, it seems that stylesheet: doc.getAttribute('stylesheet') seems to be the bit in there that's looking for the attribute from the doc and slamming in the CSS.

[bfitzpat]

Looking deeper at the AsciiDoctor.js convert options, it appears we are using different parts of the API. The browser extension is using the convertFile method (see https://asciidoctor-docs.netlify.app/asciidoctor.js/current/extend/stylesheets/) and we are using the convert method (https://github.com/redhat-developer/vscode-didact/blob/bca7f4d331e6279523ab1fd42b182fd4a64be409/src/asciidocUtils.ts#L34) because we're passing in raw text from the file.

It does not appear that convert supports the stylesheet attribute at this time. We can request it, but it seems there are a LOT of requests at the asciidoc.js github repo - https://github.com/asciidoctor/asciidoctor/issues

Is this a make or break feature @pwright ?

[bfitzpat]

Our only workaround would be offering a setting to provide additional stylesheet file configuration. We already have some code that creates links to stylesheets this way - https://github.com/redhat-developer/vscode-didact/blob/bca7f4d331e6279523ab1fd42b182fd4a64be409/src/didactWebView.ts#L306

I'm not quite sure how we'd load additional sheets on a document-by-document basis, but we could definitely add a setting that adds more stylesheets to the mix in the extension preferences.

[pwright]

@bfitzpat not a 'make or break' feature, but if there was any way (doesn't need to be specified in adoc) to override the default, that would be awesome.

[bfitzpat]

@pwright Ok, so if we have a setting that enables you to change the defaults for the stylesheets we're using now for Markdown and AsciiDoc, that would be ok? Since it would affect EVERY adoc and md file loaded for Didact, this is definitely a "use at your own risk" kind of setting.

Wondering if it would be better to add some kind of a supplemental CSS that gets loaded (also a "use at your own risk" kind of thing), but would be additive instead of replacing the defaults?

I'm just not sure how to make this user friendly enough to be a useful feature without totally breaking everything else.

And there's the added problem that there are multiple ways to load a didact file...

1. Right-click on a didact.md or didact.adoc file and select "Didact: Start Didact tutorial from file" or Ctrl+Alt+V
2. Register a Didact file with the Didact Tutorials view, then right-click on a tutorial that shows up in the list and select "Start Didact tutorial" (or click the little right-triangle button)
3. Via a vscode link (i.e. vscode://redhat.vscode-didact?https=raw.githubusercontent.com/redhat-developer/vscode-didact/master/examples/requirements.example.didact.md)

It would need to be supported by any of these methods if we set it on a per-document basis -- or supported by ALL these methods if we did it as a global setting.

There isn't the same concept as asciidoc attributes (https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions) in Markdown, though we do bring in markdown-it-attrs (https://www.npmjs.com/package/markdown-it-attrs) that may allow us to include css via css-module attributes...

The deeper I get into this, the uglier it becomes.

[bfitzpat]

@pwright made some suggestions

He wondered if we could style Didact tutorials slightly so that users could distinctly see that it's Didact and know what to expect. Something like a unique style for the first heading, a small logo in the top left (possibly do a community competition for designing it), or a header/footer that would include some details we could get from the system easily like the Didact version.

---

We can definitely add some or all of these things. I would want to make sure they're pretty unobtrusive, but we have the ability to add some custom styling whether it's Markdown or AsciiDoc and can definitely tweak various things in that extensible stylesheet.

[pwright]

@bfitzpat I think it could be very simple to begin with. I see there's already a logo at https://marketplace.visualstudio.com/items?itemName=redhat.vscode-didact so maybe just

---

Tutorial

1. Do this
2. Do that

---

Didact Version 0.1.18

---

[bfitzpat]

Something like this, but with the Didact icon in the upper right and the didact version at the bottom, with everything else scrolling?

https://www.tutorialrepublic.com/codelab.php?topic=faq&file=css-fixed-positioned-header-and-footer

[pwright]

shiny!!!

[bfitzpat]

Something like this?

[bfitzpat]

Spun off a JIRA - https://issues.redhat.com/browse/FUSETOOLS2-919

[bfitzpat]

Going back to the original purpose for this issue, I've started exploring how we might be able to use Patternfly.css (https://www.patternfly.org) instead of Bulma or the AsciiDoc CSS.

Problems I see...

• patternfly,css is MASSIVE. Even if we go with patternfly.min.css, it's still a huge wall of text that I'm not sure we need all of.
• If we go with PatternFly, what do we do with theming in VS Code? I suspect that theming goes away and we are left with the PatternFly color scheme? It seems to have some light/dark theme capabilities so perhaps we can reference, but I am out of my depth even pondering such work.

If you look at https://github.com/redhat-developer/vscode-didact/blob/master/media/webviewslim.css, you'll see the minimum amount of change needed to make Bulma (https://cdn.jsdelivr.net/npm/bulma@0.8.0/css/bulma.min.css) and the AsciiDoctor (https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor@v2.0.10/data/stylesheets/asciidoctor-default.css) CSS files to work in Didact. Maybe it's just a matter of trying to adapt?

If we want Didact files in Che/CRW to jive with the look/feel of the OpenShift Console, we may need to get some help from our UX folks to help style these Didact files a bit more easily. If we get that, it should just be a matter of providing a setting to overwrite the CSS settings we are using now.

We are pulling in the css in these two places:

• https://github.com/redhat-developer/vscode-didact/blob/be7b3c01716a14753ae4bec236aea73d4035ebc1/src/didactPanel.ts#L261
• https://github.com/redhat-developer/vscode-didact/blob/be7b3c01716a14753ae4bec236aea73d4035ebc1/src/didactPanel.ts#L304