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

✅ 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>
```

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

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