Understanding hastscript: Building HAST Nodes in Astro

Introduction

When working with Markdown in Astro, you’ll often need to transform or create HTML elements programmatically. This is where hastscript comes in - a powerful utility that allows you to build HTML Abstract Syntax Trees (HAST) using a JSX-like syntax.

In this guide, we’ll explore how hastscript is used in Astro projects, particularly in custom remark and rehype plugins.

What is hastscript?

hastscript (Hypertext Abstract Syntax Tree Script) is a utility that creates HAST nodes - the same structure used by rehype and remark plugins to represent HTML. Think of it as a way to write HTML in JavaScript without using strings.

Why Use hastscript?

Type-safe: Creates proper HAST nodes with correct structure
Clean syntax: Similar to JSX but in pure JavaScript
Integration: Works seamlessly with remark/rehype ecosystem
Maintainable: Easier to modify than string concatenation

Installation

1
npm install hastscript

Basic Syntax

The basic syntax of hastscript is:

1
h(tagName, properties, children)

Where:

tagName: HTML element name (string)
properties: Object containing attributes (optional)
children: Array of child nodes or text content (optional)

Simple Examples

Creating a Div Element

1
import { h } from 'hastscript';
2

3
// Simple div
4
const node = h('div', 'Hello World');
5

6
// Result (HAST):
7
// {
8
//   type: 'element',
9
//   tagName: 'div',
10
//   properties: {},
11
//   children: [{ type: 'text', value: 'Hello World' }]
12
// }

Adding Classes and Attributes

1
// Div with class
2
const divWithClass = h('div', { className: 'container' }, 'Content');
3

4
// Multiple classes
5
const multiClass = h('div', { className: ['card', 'shadow-lg'] }, 'Card content');
6

7
// With ID and data attributes
8
const withAttrs = h('div', {
9
  id: 'main',
10
  className: 'wrapper',
11
  dataTheme: 'dark'
12
}, 'Content');

Creating Links

1
// Simple link
2
const link = h('a', { href: 'https://example.com' }, 'Click here');
3

4
// Link with target and rel
5
const externalLink = h('a', {
6
  href: 'https://example.com',
7
  target: '_blank',
8
  rel: 'noopener noreferrer'
9
}, 'External link');

Nested Elements

You can create complex nested structures by passing arrays of child elements:

1
import { h } from 'hastscript';
2

3
const card = h('div', { className: 'card' }, [
4
  h('h2', { className: 'card-title' }, 'Card Title'),
5
  h('p', { className: 'card-description' }, 'This is a description'),
6
  h('button', { className: 'btn' }, 'Click Me')
7
]);

Real-World Usage in Astro

Custom Remark Plugin Example

Here’s how hastscript is used in a custom remark plugin to create custom components:

1
import { h } from 'hastscript';
2
import { visit } from 'unist-util-visit';
3

4
export function remarkCustomButton() {
5
  return (tree) => {
6
    visit(tree, 'text', (node, index, parent) => {
7
      const match = node.value.match(/\[button:(.+?)\]\((.+?)\)/);
8

9
      if (match) {
10
        const [, text, href] = match;
11

12
        // Create button element using hastscript
13
        const buttonNode = h('a', {
14
          href: href,
15
          className: ['btn', 'btn-primary'],
8 collapsed lines
16
          role: 'button'
17
        }, text);
18

19
        parent.children[index] = buttonNode;
20
      }
21
    });
22
  };
23
}

Creating Alert/Admonition Boxes

1
function createAdmonition(type, title, content) {
2
  const iconMap = {
3
    note: '📝',
4
    tip: '💡',
5
    warning: '⚠️',
6
    danger: '🚨'
7
  };
8

9
  return h('div', {
10
    className: ['admonition', `admonition-${type}`],
11
    dataType: type
12
  }, [
13
    h('div', { className: 'admonition-title' }, [
14
      h('span', { className: 'admonition-icon' }, iconMap[type]),
15
      h('strong', title)
7 collapsed lines
16
    ]),
17
    h('div', { className: 'admonition-content' }, content)
18
  ]);
19
}
20

21
// Usage
22
const noteBox = createAdmonition('note', 'Important Note', 'This is a note');

Working with Custom Elements

Creating Code Blocks with Syntax Highlighting

1
function createCodeBlock(code, language) {
2
  return h('div', { className: 'code-wrapper' }, [
3
    h('div', { className: 'code-header' }, [
4
      h('span', { className: 'language-badge' }, language),
5
      h('button', {
6
        className: 'copy-button',
7
        dataCode: code
8
      }, 'Copy')
9
    ]),
10
    h('pre', [
11
      h('code', { className: `language-${language}` }, code)
12
    ])
13
  ]);
14
}

Creating Cards with Images

1
function createImageCard(imgSrc, title, description, linkUrl) {
2
  return h('div', { className: 'image-card' }, [
3
    h('img', {
4
      src: imgSrc,
5
      alt: title,
6
      className: 'card-image',
7
      loading: 'lazy'
8
    }),
9
    h('div', { className: 'card-body' }, [
10
      h('h3', { className: 'card-title' }, title),
11
      h('p', { className: 'card-description' }, description),
12
      h('a', {
13
        href: linkUrl,
14
        className: 'card-link'
15
      }, 'Read more →')
3 collapsed lines
16
    ])
17
  ]);
18
}

hastscript in Astro Plugin Example

Here’s a complete example of a remark plugin using hastscript in an Astro project:

1
import { h } from 'hastscript';
2
import { visit } from 'unist-util-visit';
3

4
export function remarkGithubCard() {
5
  return (tree) => {
6
    visit(tree, 'text', (node, index, parent) => {
7
      // Match pattern: [github:username/repo]
8
      const match = node.value.match(/\[github:([^/]+)\/([^\]]+)\]/);
9

10
      if (match) {
11
        const [, username, repo] = match;
12
        const repoUrl = `https://github.com/${username}/${repo}`;
13

14
        // Create GitHub card using hastscript
28 collapsed lines
15
        const githubCard = h('div', { className: 'github-card' }, [
16
          h('div', { className: 'github-card-header' }, [
17
            h('svg', {
18
              className: 'github-icon',
19
              viewBox: '0 0 16 16',
20
              width: '16',
21
              height: '16'
22
            }, [
23
              h('path', {
24
                fill: 'currentColor',
25
                d: 'M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z'
26
              })
27
            ]),
28
            h('span', { className: 'github-repo-name' }, `${username}/${repo}`)
29
          ]),
30
          h('a', {
31
            href: repoUrl,
32
            target: '_blank',
33
            rel: 'noopener noreferrer',
34
            className: 'github-link'
35
          }, 'View on GitHub →')
36
        ]);
37

38
        parent.children[index] = githubCard;
39
      }
40
    });
41
  };
42
}

Using the Plugin in Astro Config

1
import { defineConfig } from 'astro/config';
2
import { remarkGithubCard } from './src/plugins/remark-github-card.js';
3

4
export default defineConfig({
5
  markdown: {
6
    remarkPlugins: [
7
      remarkGithubCard
8
    ]
9
  }
10
});

Common Patterns

Creating Containers with Multiple Children

1
// Creating a tab container
2
const tabs = h('div', { className: 'tabs' }, [
3
  h('div', { className: 'tab-headers' }, [
4
    h('button', { className: 'tab-button active', dataTab: 'tab1' }, 'Tab 1'),
5
    h('button', { className: 'tab-button', dataTab: 'tab2' }, 'Tab 2'),
6
    h('button', { className: 'tab-button', dataTab: 'tab3' }, 'Tab 3')
7
  ]),
8
  h('div', { className: 'tab-content' }, [
9
    h('div', { className: 'tab-pane active', id: 'tab1' }, 'Content 1'),
10
    h('div', { className: 'tab-pane', id: 'tab2' }, 'Content 2'),
11
    h('div', { className: 'tab-pane', id: 'tab3' }, 'Content 3')
12
  ])
13
]);

Conditional Attributes

1
function createButton(text, options = {}) {
2
  const { href, disabled, variant = 'primary' } = options;
3

4
  const props = {
5
    className: ['btn', `btn-${variant}`],
6
    ...(disabled && { disabled: true }),
7
    ...(href && { href })
8
  };
9

10
  return h(href ? 'a' : 'button', props, text);
11
}
12

13
// Usage
14
const linkButton = createButton('Click', { href: '/page', variant: 'secondary' });
15
const disabledButton = createButton('Disabled', { disabled: true });

hastscript Shortcuts

Using Selectors (CSS-like syntax)

1
// Instead of:
2
h('div', { className: 'container' })
3

4
// You can write:
5
h('div.container')
6

7
// Multiple classes:
8
h('div.card.shadow-lg')
9

10
// With ID:
11
h('div#main.container')
12

13
// Combination:
14
h('section#about.section.dark-theme')

Tips and Best Practices

1. Keep Components Reusable

1
// Good - reusable function
2
function createHighlight(text, color) {
3
  return h('span', {
4
    className: 'highlight',
5
    style: `background-color: ${color}`
6
  }, text);
7
}
8

9
// Bad - hardcoded values
10
const highlight = h('span', {
11
  className: 'highlight',
12
  style: 'background-color: yellow'
13
}, 'hardcoded text');

2. Type Safety with TypeScript

1
import { h } from 'hastscript';
2
import type { Element } from 'hast';
3

4
function createAlert(message: string, type: 'info' | 'warning' | 'error'): Element {
5
  return h('div', {
6
    className: ['alert', `alert-${type}`],
7
    role: 'alert'
8
  }, message);
9
}

3. Handle Text Safely

1
// Safe text handling
2
function createParagraph(text) {
3
  return h('p', { className: 'paragraph' },
4
    typeof text === 'string' ? text : String(text)
5
  );
6
}

4. Compose Complex Structures

1
function createArticle({ title, author, date, content }) {
2
  return h('article', { className: 'blog-post' }, [
3
    createHeader(title, author, date),
4
    createContent(content),
5
    createFooter()
6
  ]);
7
}
8

9
function createHeader(title, author, date) {
10
  return h('header', { className: 'post-header' }, [
11
    h('h1', title),
12
    h('div', { className: 'post-meta' }, [
13
      h('span', { className: 'author' }, author),
14
      h('time', { dateTime: date }, formatDate(date))
15
    ])
2 collapsed lines
16
  ]);
17
}

Debugging hastscript Nodes

To see what HAST structure is created:

1
import { h } from 'hastscript';
2
import { toHtml } from 'hast-util-to-html';
3

4
const node = h('div.container', [
5
  h('h1', 'Hello'),
6
  h('p', 'World')
7
]);
8

9
// Convert to HTML string for debugging
10
console.log(toHtml(node));
11
// Output: <div class="container"><h1>Hello</h1><p>World</p></div>
12

13
// Inspect HAST structure
14
console.log(JSON.stringify(node, null, 2));

Common Use Cases in Astro

1. Custom Markdown Syntax

Create custom syntax that transforms into HTML components

2. Plugin Development

Build remark/rehype plugins for content transformation

3. Component Wrapping

Wrap existing content with custom containers

4. Dynamic Content Generation

Generate HTML structures based on frontmatter or external data

5. Accessibility Enhancements

Add ARIA attributes and semantic HTML programmatically

Resources

Conclusion

hastscript is an essential tool when working with Markdown processing in Astro. It provides a clean, type-safe way to create HTML structures programmatically, making your plugins more maintainable and reliable.

By mastering hastscript, you can:

Create custom Markdown extensions
Build reusable content components
Transform content dynamically
Maintain clean, readable code

Start experimenting with hastscript in your next Astro project, and you’ll discover how powerful it can be for content transformation!

Have questions or suggestions? Feel free to reach out or leave a comment below. Happy coding! 🚀