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.

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

feat(pv-stylemark): add suport for js and html executable code blocks support the hidden attribute #224

Conversation

mbehzad
Copy link
Contributor

@mbehzad mbehzad commented Apr 11, 2024

== Description ==
The original stylemark allowed different types of fenced code blocks that contained the content for the examples: Executable code blocks spec

This PR will add support for these two variations:

```example.js
console.log();
```

```example.html
<button></button>
```

The embeded html code is handy if the components are mostly self rendering custom elements which don't need much html. This will allow to showcase them in different variations better integrated in the markdown (e.g. each option is described and an example added right after. without the need to create a hbs file for each example or put all examples in the same page)

Also added support for the hidden attribute (or rather the lack of). This is mainly to provide backwards compatibility and the use case is something like this where you want to execute some code and also show it in the readme at the same time.

Use the dialog as a modal:

```example.js
dialog.modal = true;
dialog.open();
```

```example:dialog.html
```

What is still missing is support for js and css files:

```example:path/to/script.js
```

But it is a little unclear e.g. the path is relative to where? the target folder as is for the html files or the markdown file in the src where the developer is writing the content and then do they expect stylemark to copy those files to target? does it need to maintain the same folder structure or can they be copied flat to styleguide? how they should be loaded, in head or in body? as sync script or async or type module etc? or make these all configurable?


Right now of course the new styleguide needs to be backwards compatible to make the transition easier, but i would argue for instead of the original stylemark pattern example.html change it to html example:

```css example
foo {
  display: none;
}
```

This is more markdown spec comform and allows the IDE's to syntax highlight the content. similarly for referenced files i would also replace the : notation with using a space for more consistence, easier readability for the developer and easier parsing for us. (key=value pairs is also an option that has precedence ) This would allow passing query params or even load the files with some other extension. Or even have additional options hidden, collapsed, height of iframe etc.


```html example demo/comp.html?foo=bar#anchor height=content collapsed=true
```

```js example http://cdn/lib.mjs type=module hidden
```

== Closes issue(s) ==

== Changes ==

== Affected Packages ==
pv-stylemark

mbehzad added 2 commits April 10, 2024 15:08
…tyleguide to the new stlymark

this will allow in multi-tenant codebases for easier distinguishing between component with the same
name
…ithout modification

introduce the `raw` option that can be set via params of the code block, front matter of the
markdown or config.stlyemark.yaml's `examples` section and won't wrap the markup with `htmlHead`,
`bodyHtml` etc from the config when set.
 Also introduce a new experimental pattern for how the
code blocks can be written to be picked up by the stylemark. i.e. `css example-1 hidden` or `html
example-1 ./demo/file.html?foo=bar#anchor raw=true hidden`

fix #227
@mbehzad
Copy link
Contributor Author

mbehzad commented Apr 15, 2024

commit c5a5e66 adds support for the new pattern css example hidden or html ./demo/file.html?query=param#anchor raw=false.
The old pattern is sill valid (but won't support e.g. query params or hash)

feat(pv-stylemark): add info regarding the source of the components s…
@friewerts friewerts merged commit 9c2c837 into feature/stylemark-executable-code-blocks Apr 25, 2024
3 checks passed
@friewerts friewerts deleted the feature/stylemark-executable-code-blocks--scripts branch April 25, 2024 10:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

2 participants