@codady/coax

Coax: A Code Syntax Highlighter for Web Components

Overview

Coax is a custom web component that enables syntax highlighting for various programming languages inside your HTML documents. It allows you to easily embed highlighted code using web standards (Web Components) and modern CSS. This plugin automatically highlights code using regular expressions and supports dynamic theming and customization.

Features

• Custom Web Component: Easily use <ax-code> to render syntax-highlighted code.
• Language Support: Register custom language configurations for syntax highlighting (e.g., HTML, CSS, JavaScript, TypeScript).
• Custom Themes: Add language-specific themes using CSS variables for customization.
• Shadow DOM: Isolated styling and functionality using the Shadow DOM for better encapsulation.
• Dynamic CSS: Dynamically generate styles for each language based on rules.

Installation

Simply include the Coax JavaScript file in your project, or use the module system if you're using a build tool like Webpack or Rollup.

Direct inclusion (via script tag)

<script src="path/to/coax.js"></script>

Usage

To use the Coax code highlighting component, follow these steps:

1. Define the <ax-code> element

<ax-code lang="js">
  // Your JavaScript code here
</ax-code>

<ax-code lang="css">
  /* Your CSS code here */
</ax-code>

<ax-code lang="html">
  <!-- Your HTML code here -->
</ax-code>

2. Register Language Configurations

You can register languages with their syntax rules and themes using the Coax.register method.

Coax.register('html', {
  rules: [
    { name: 'comment', reg: /<!--[\s\S]*?-->/ },
    { name: 'tag', reg: /<\/?[a-zA-Z0-9]+/ },
    { name: 'attr', reg: /[a-zA-Z-]+(?=\s*=\s*)/ },
    { name: 'string', reg: /(['"])(?:\\.|[^\\])*?\1/ },
  ],
  theme: {
    'tag': '#e06c75', // red
    'attr': '#d19a66', // orange
    'string': '#98c379', // green
  }
});

3. Customization

You can customize the code highlighting by modifying the language's rules, theme colors, or internal CSS using the theme, internalCss, and cssPrefix properties.

Example:

Coax.register('css', {
  rules: [
    { name: 'comment', reg: /\/\*[\s\S]*?\*\// },
    { name: 'property', reg: /[a-z-]+(?=\s*:)/ },
    { name: 'selector', reg: /[.#a-z0-9, \n\t>:+()_-]+(?=\s*\{)/i },
    { name: 'unit', reg: /(?<=\d)(px|em|rem|%|vh|vw|ms|s|deg)/ },
  ],
  theme: {
    'keyword': '#61afef', // blue
    'string': '#98c379', // green
    'op': '#abb2bf', // gray
  },
  internalCss: `
    .ax-css-string { color: var(--ax-code-string); }
  `
});

4. Optional Attributes

You can customize the code block's height and max height:

<ax-code lang="js" height="200px" max-height="400px">
  const x = 10;
</ax-code>

Development

If you'd like to extend or modify the plugin, the source code is available for you to contribute or adapt.

• Clone the repository: git clone https://github.com/your-repository
• Run build tools (e.g., Webpack, Babel) for production optimization.

License

MIT License. Feel free to use and modify it for your projects.

中文文档

概述

Coax 是一个自定义 Web 组件，可以在 HTML 文档中嵌入高亮的代码。它允许您使用现代 Web 标准（Web 组件）和 CSS 来轻松实现代码高亮。该插件通过正则表达式自动高亮代码，并支持动态主题和自定义设置。

特性

• 自定义 Web 组件：使用 <ax-code> 标签轻松渲染代码高亮。
• 语言支持：为每种编程语言注册自定义语法高亮配置（例如，HTML，CSS，JavaScript，TypeScript）。
• 自定义主题：使用 CSS 变量添加语言特定的主题，支持个性化定制。
• Shadow DOM：使用 Shadow DOM 实现样式和功能的隔离。
• 动态 CSS：基于规则动态生成每种语言的样式。

安装

只需将 Coax 的 JavaScript 文件包含到您的项目中，或使用构建工具（如 Webpack 或 Rollup）进行模块化引入。

直接引入（通过 <script> 标签）

<script src="path/to/coax.js"></script>

使用方法

要使用 Coax 代码高亮组件，请按照以下步骤进行操作：

1. 定义 <ax-code> 元素

<ax-code lang="js">
  // 这里是您的 JavaScript 代码
</ax-code>

<ax-code lang="css">
  /* 这里是您的 CSS 代码 */
</ax-code>

<ax-code lang="html">
  <!-- 这里是您的 HTML 代码 -->
</ax-code>

2. 注册语言配置

您可以使用 Coax.register 方法注册语言的语法规则和主题。

Coax.register('html', {
  rules: [
    { name: 'comment', reg: /<!--[\s\S]*?-->/ },
    { name: 'tag', reg: /<\/?[a-zA-Z0-9]+/ },
    { name: 'attr', reg: /[a-zA-Z-]+(?=\s*=\s*)/ },
    { name: 'string', reg: /(['"])(?:\\.|[^\\])*?\1/ },
  ],
  theme: {
    'tag': '#e06c75', // 红色
    'attr': '#d19a66', // 橙色
    'string': '#98c379', // 绿色
  }
});

3. 自定义设置

您可以通过修改语言的规则、主题颜色或内部 CSS 来定制代码高亮，具体方法如下：

Coax.register('css', {
  rules: [
    { name: 'comment', reg: /\/\*[\s\S]*?\*\// },
    { name: 'property', reg: /[a-z-]+(?=\s*:)/ },
    { name: 'selector', reg: /[.#a-z0-9, \n\t>:+()_-]+(?=\s*\{)/i },
    { name: 'unit', reg: /(?<=\d)(px|em|rem|%|vh|vw|ms|s|deg)/ },
  ],
  theme: {
    'keyword': '#61afef', // 蓝色
    'string': '#98c379', // 绿色
    'op': '#abb2bf', // 灰色
  },
  internalCss: `
    .ax-css-string { color: var(--ax-code-string); }
  `
});

4. 可选属性

您可以通过 height 和 max-height 属性自定义代码块的高度和最大高度：

<ax-code lang="js" height="200px" max-height="400px">
  const x = 10;
</ax-code>

许可证

MIT 许可证。可以自由使用和修改代码以适应您的项目需求。

---