Markdown <> Web Components Formatting Issues #1267

thescientist13 · 2024-08-14T01:59:58Z

thescientist13
Aug 14, 2024
Maintainer

Overview

As part of working ProjectEvergreen/www.greenwoodjs.dev#57 for the new website, noticed a few rough edges with using markdown and Web Component / Web Component adjacent HTML.

✅ Code fences have to be left aligned
✅ Prettier left aligning content automatically
❓ Line breaks introduces <p> tags
❓ <template> tag breaks parsing / highlighting
❓ HTML in JavaScript in html fences breaks
❓ Custom Elements getting wrapped in <p> tags

✅ Code fences have to be left aligned

Seems to work just fine after all 🤷‍♂️ - #1267 (comment)

Currently, it seems we can't indent code fences in markdown, like in this "card" example.

<div class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>

```shell
src/
  pages/
    api/
      search.js       # API route
    index.html        # Static (SSG)
    products.js       # Dynamic (SSR), or emit as static with pre-rendering
    about.md          # markdown also supported
```

</div>

Would like it to be able to be formatted like this

<div class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>

  ```shell
  src/
    pages/
      api/
        search.js       # API route
      index.html        # Static (SSG)
      products.js       # Dynamic (SSR), or emit as static with pre-rendering
      about.md          # markdown also supported
  ```

</div>

Can't seem to reproduce anymore?? 🤔

✅ Prettier left aligning content automatically

Found a decent enough solution in this thread - #1267 (comment)

<section class="top">

<app-latest-post
    link="/blog/release/v0.30.0/"
    title="We just launched v0.30.0">
</app-latest-post>

<app-hero-banner></app-hero-banner>

❓ Line breaks introduce `<p>` tags

<app-latest-post
  link="/blog/release/v0.30.0/"
  title="We just launched v0.30.0">
</app-latest-post>

Instead have to do it all on one line

<app-latest-post link="/blog/release/v0.30.0/" title="We just released v0.30.0"></app-latest-post>

❓ `<template>` tag breaks parsing / highlighting - #1267 (comment)

This would be nice since otherwise, we have to manually hide the <div> with inline CSS.

<!-- using a template tag breaks parsing -->
<template class="walkthrough-card card3">
  <span>JS Second</span>
  <p>Yay JavaScript</p>

  ```js
  console.log('hello world!');
  ```
</template>

I think this is just an issue with re-thinking how to manipulate the DOM since a <template> may not have DOM methods like a <div>

❓ HTML in JavaScript in `html` fences breaks

Noticed in this feature to the website while working on a copy / paste component, that when I had custom element wrapping an HTML fenced markdown block, which itself had HTML inside it...

<app-ctc-block variant="snippet" heading="src/components/greeting.js">

  ```html
  <html>
    <head>
      <script type="module">
        import { html, css, LitElement } from "lit";

        export class SimpleGreeting extends LitElement {
          static styles = css`
            p {
              color: blue;
            }
          `;

          static properties = {
            name: { type: String },
          };

          constructor() {
            super();
            this.name = "Somebody";
          }

          render() {
            return html`<p>Hello, ${this.name}!</p>`;
          }
        }
        customElements.define("simple-greeting", SimpleGreeting);
      </script>
    </head>

    <body>
      <simple-greeting></simple-greeting>
      <simple-greeting name="Greenwood"></simple-greeting>
    </body>
  </html>
  ```

</app-ctc-block>

it broke the output renderering; missing <p> tag in the render function with a line break, and ending HTML tags are missing their opening <

and confirmed with the HTML output to the clipboard

<html>
  <head>
    <script type="module">
      import { html, css, LitElement } from "lit";

      export class SimpleGreeting extends LitElement {
        // ...

        render() {
          return html`Hello, ${this.name}!`;
        }
      }
      customElements.define("simple-greeting", SimpleGreeting);
    script>
  head>

  <body>
    <simple-greeting>simple-greeting>
    <simple-greeting name="Greenwood">simple-greeting>
  body>
html>

It should look like this

The resolution for now was to just make it a pure JS example

<app-ctc-block variant="snippet" heading="src/components/greeting.js">

  ```js
  import { html, css, LitElement } from "lit";

  export class SimpleGreeting extends LitElement {
    static styles = css`
      p {
        color: blue;
      }
    `;

    static properties = {
      name: { type: String },
    };

    constructor() {
      super();
      this.name = "Somebody";
    }

    render() {
      return html`<p>Hello, ${this.name}!</p>`;
    }
  }
  ```

</app-ctc-block>
```

❓ Custom Element "Unwrapping" Plugin for Unified

Pulled over from #568

As observed in #554 in support of #529, when using a custom element in markdown

# My Page

<my-component></my-component>

It will come out wrapped in a <p> tag,

<h1>My Page</h1>

<p>
  <my-component></my-component>
</p>

It was necessary to "unwrap" these when serializing with puppeteer or else we got duplicate light / shadow dom rendering, like we had observed in #433.

So the thought here is, make a unified plugin for this and use a parser instead? Actually, not sure if this an issue when not using Puppeteer (e.g. WCC or Lit SSR) so maybe this can be moved to the Puppeteer plugin only instead of in Greenwood?

thescientist13 · 2024-08-15T00:29:50Z

thescientist13
Aug 15, 2024
Maintainer Author

Well well, I guess this seems to be working after all? 😮 🤷‍♂️

<div class="capabilities-content item4">
  <span>API Routes</span>
  <i>api-routes.svg</i>
  <p>Need client side data fetching or mutations?  Greenwood provides API routes out of the box that are fully invested in web standards like <em>Fetch</em> and <em>FormData</em>.  Of course it is all fully compatible with server-rendering Web Components; a perfect companion for HTML over the wire solutions!</p>

  ```js
  // src/pages/api/search.js
  import { renderFromHTML } from "wc-compiler";
  import { getProducts } from "../lib/db.js";

  export async function handler(request) {
    const formData = await request.formData();
    const searchTerm = formData.has("term") ? formData.get("term") : "";
    const products = await getProducts(searchTerm);
    const { html } = await renderFromHTML(
      `
      ${products
        .map((item, idx) => {
          const { title, thumbnail } = item;

          return `
            <app-card
              title="${idx + 1}) ${title}"
              thumbnail="${thumbnail}"
            ></app-card>
          `;
        })
        .join("")}
    `,
      [new URL("../components/card.js", import.meta.url)],
    );

    return new Response(html, {
      headers: new Headers({
        "Content-Type": "text/html",
      }),
    });
  }
  ```

</div>

0 replies

thescientist13 · 2024-08-15T00:44:28Z

thescientist13
Aug 15, 2024
Maintainer Author

So now that it seems there is indeed no issue with indenting code fences with markdown, trying to test for Prettier automatically de-indenting said blocks, e.g.

<!-- desired formatting -->
<div class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>

  ```shell
  src/
    pages/
      api/
        search.js       # API route
      index.html        # Static (SSG)
      products.js       # Dynamic (SSR), or emit as static with pre-rendering
      about.md          # markdown also supported
  ```

</div>

<!-- current formatting by Prettier -->
<div class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>

```shell
src/
  pages/
    api/
      search.js       # API route
    index.html        # Static (SSG)
    products.js       # Dynamic (SSR), or emit as static with pre-rendering
    about.md          # markdown also supported
```

</div>

I found this embeddedLanguageFormatting option to "off", but doesn't seem to change anything about the formatting. 😞

Using  doesn't seem to work either, but I think this only applies to formatting of the code fence itself? 😞 😞

1 reply

thescientist13 Aug 15, 2024
Maintainer Author

Ok, this combination seems to work

<!-- prettier-ignore-start -->
<div class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>

  ```shell
  src/
    pages/
      api/
        search.js       # API route
      index.html        # Static (SSG)
      products.js       # Dynamic (SSR), or emit as static with pre-rendering
      about.md          # markdown also supported
  ```
</div>

<!-- prettier-ignore-end -->
```

The line break before `<!-- prettier-ignore-end -->` seems to be pretty important.  Not ideal, but works for now 😮‍💨

thescientist13 · 2024-08-15T01:31:40Z

thescientist13
Aug 15, 2024
Maintainer Author

Yeah, so the main issue with <template> is that nested content is not escaped

<template class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>

  ```shell
  src/
    pages/
      api/
        search.js       # API route
      index.html        # Static (SSG)
      products.js       # Dynamic (SSR), or emit as static with pre-rendering
      about.md          # markdown also supported
  ```
</template>

comes out as

<template class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>
<pre><code class="language-shell">src/
  pages/
    api/
      search.js       # API route
    index.html        # Static (SSG)
    products.js       # Dynamic (SSR), or emit as static with pre-rendering
    about.md          # markdown also supported
</code></pre>
</template>

Instead of with all the token, etc classes from Prism

<div class="capabilities-content item1">
  <span>Hybrid Routing</span>
  <i>html.svg</i>
  <p>Greenwood is HTML first by design.  Start from just an <em>index.html</em> file or leverage <strong>hybrid, file-system based routing</strong> to easily achieve static and dynamic pages side-by-side.  Single Page Applications (SPA) also supported.</p>
<pre class="language-shell"><code class="language-shell">src/
  pages/
    api/
      search.js       <span class="token comment"># API route</span>
    index.html        <span class="token comment"># Static (SSG)</span>
    products.js       <span class="token comment"># Dynamic (SSR), or emit as static with pre-rendering</span>
    about.md          <span class="token comment"># markdown also supported</span>
</code></pre>
</div>

Wonder if it's the prism highlighter package? 🤔

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Markdown <> Web Components Formatting Issues #1267

{{title}}

{{editor}}'s edit

{{editor}}'s edit

Replies: 3 comments 1 reply

{{title}}

{{title}}

{{editor}}'s edit

{{editor}}'s edit

{{title}}

{{title}}

Select a reply

Markdown <> Web Components Formatting Issues #1267

thescientist13 Aug 14, 2024 Maintainer

Overview

✅ Code fences have to be left aligned

✅ Prettier left aligning content automatically

❓ Line breaks introduce <p> tags

❓ <template> tag breaks parsing / highlighting - #1267 (comment)

❓ HTML in JavaScript in html fences breaks

❓ Custom Element "Unwrapping" Plugin for Unified

Replies: 3 comments · 1 reply

thescientist13 Aug 15, 2024 Maintainer Author

thescientist13 Aug 15, 2024 Maintainer Author

thescientist13 Aug 15, 2024 Maintainer Author

thescientist13 Aug 15, 2024 Maintainer Author

thescientist13
Aug 14, 2024
Maintainer

❓ Line breaks introduce `<p>` tags

❓ `<template>` tag breaks parsing / highlighting - #1267 (comment)

❓ HTML in JavaScript in `html` fences breaks

Replies: 3 comments 1 reply

thescientist13
Aug 15, 2024
Maintainer Author

thescientist13
Aug 15, 2024
Maintainer Author

thescientist13 Aug 15, 2024
Maintainer Author

thescientist13
Aug 15, 2024
Maintainer Author