hexo-renderer-mdx 1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,162 @@
+# Contributing to hexo-renderer-mdx
+
+Thank you for your interest in contributing! This document provides guidelines for contributing to the project.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/hexo-renderer-mdx.git
+   cd hexo-renderer-mdx
+   ```
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+```
+
+This runs both basic and advanced test suites that validate:
+- MDX compilation
+- Markdown rendering
+- JSX element rendering
+- Custom components
+- Dynamic content
+- Front matter handling
+
+### Adding New Features
+
+1. Create a new branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes to `index.js`
+
+3. Add tests if applicable:
+   - Add test cases to `test/` directory
+   - Update `test.js` or `test-advanced.js` as needed
+
+4. Run tests to ensure nothing is broken:
+   ```bash
+   npm test
+   ```
+
+5. Commit your changes:
+   ```bash
+   git add .
+   git commit -m "Add: your feature description"
+   ```
+
+6. Push to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+7. Open a Pull Request
+
+## Code Style
+
+- Use single quotes for strings
+- Use 2 spaces for indentation
+- Add JSDoc comments for functions
+- Follow existing code patterns
+
+## Pull Request Guidelines
+
+- Keep PRs focused on a single feature or fix
+- Update documentation if needed
+- Ensure all tests pass
+- Add tests for new features
+- Update README.md if adding user-facing changes
+
+## Reporting Issues
+
+When reporting issues, please include:
+- Hexo version
+- Node.js version
+- hexo-renderer-mdx version
+- Steps to reproduce
+- Expected vs actual behavior
+- Error messages (if any)
+
+## Publishing (Maintainers Only)
+
+### Setup - Trusted Publishing
+
+This package uses **Trusted Publishing** (OIDC) for secure, token-free publishing to npm.
+
+1. **Create an npm account** at https://www.npmjs.com if you don't have one
+
+2. **Configure Trusted Publishing on npm**:
+   - Publish the package manually first time: `npm publish --access public`
+   - Go to https://www.npmjs.com/package/hexo-renderer-mdx/access
+   - Navigate to "Publishing" → "Trusted Publishers"
+   - Click "Add trusted publisher"
+   - Fill in the details:
+     - **Provider**: GitHub Actions
+     - **Repository owner**: Bryan0324
+     - **Repository name**: hexo-renderer-mdx
+     - **Workflow file**: publish.yml
+     - **Environment name**: (leave empty)
+   - Click "Add"
+
+No npm tokens needed! The workflow uses OpenID Connect (OIDC) to authenticate securely.
+
+### Publishing a New Version
+
+1. **Update version** in `package.json`:
+   ```bash
+   npm version patch  # for bug fixes (1.0.0 → 1.0.1)
+   npm version minor  # for new features (1.0.0 → 1.1.0)
+   npm version major  # for breaking changes (1.0.0 → 2.0.0)
+   ```
+
+2. **Push changes and tags**:
+   ```bash
+   git push
+   git push --tags
+   ```
+
+3. **Create a GitHub Release**:
+   - Go to https://github.com/Bryan0324/hexo-renderer-mdx/releases
+   - Click "Draft a new release"
+   - Choose the tag you just created
+   - Add release title (e.g., "v1.0.1")
+   - Add release notes describing changes
+   - Click "Publish release"
+
+4. **GitHub Action will automatically**:
+   - Checkout the code
+   - Install dependencies
+   - Run tests
+   - Publish to npm with provenance using Trusted Publishing
+   - Make the package publicly available
+
+5. **Verify publication**:
+   - Check https://www.npmjs.com/package/hexo-renderer-mdx
+   - Verify the new version is listed
+   - Check that provenance is displayed
+
+### Manual Publishing (If Needed)
+
+If you need to publish manually:
+
+```bash
+# Login to npm
+npm login
+
+# Publish
+npm publish --access public
+```
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 grass-cat//Bryan0324
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,378 @@
+# hexo-renderer-mdx
+
+A [Hexo](https://hexo.io/) renderer plugin for [MDX](https://mdxjs.com/) - Markdown with JSX support. This plugin allows you to write Hexo posts and pages using MDX, enabling you to embed React components directly in your markdown content.
+
+## Features
+
+- 🚀 Full MDX support with JSX syntax
+- ⚛️ React component integration
+- 📝 Markdown compatibility
+- 🎨 Custom component support
+- 🔥 Fast compilation with @mdx-js/mdx
+
+## Installation
+
+```bash
+npm install hexo-renderer-mdx --save
+```
+
+or with yarn:
+
+```bash
+yarn add hexo-renderer-mdx
+```
+
+## How to Use
+
+### Quick Start
+
+1. **Install the plugin** in your Hexo blog directory:
+
+   ```bash
+   npm install hexo-renderer-mdx --save
+   ```
+
+2. **Create your first MDX post** in `source/_posts/my-first-mdx-post.mdx`:
+
+   ```mdx
+   ---
+   title: My First MDX Post
+   date: 2026-01-06
+   tags: [hexo, mdx]
+   ---
+
+   # Hello from MDX!
+
+   This is regular markdown **with bold text**.
+
+   <div style={{ 
+     padding: '20px', 
+     backgroundColor: '#e3f2fd',
+     borderRadius: '8px',
+     marginTop: '20px'
+   }}>
+     🎉 This is a styled JSX element!
+   </div>
+   ```
+
+3. **Generate your site**:
+
+   ```bash
+   hexo generate
+   ```
+
+4. **Preview locally**:
+
+   ```bash
+   hexo server
+   ```
+
+5. **View your post** at `http://localhost:4000`
+
+That's it! The plugin automatically processes all `.mdx` files in your Hexo blog.
+
+### Step-by-Step Guide
+
+#### 1. Setting Up a New Hexo Blog (Optional)
+
+If you don't have a Hexo blog yet:
+
+```bash
+npm install -g hexo-cli
+hexo init my-blog
+cd my-blog
+npm install
+```
+
+#### 2. Installing the Plugin
+
+In your Hexo blog directory:
+
+```bash
+npm install hexo-renderer-mdx --save
+```
+
+No additional configuration is needed - the plugin registers automatically!
+
+#### 3. Creating MDX Files
+
+MDX files work just like regular Markdown files, but with JSX support. Create files in:
+- `source/_posts/` for blog posts
+- `source/` for pages
+
+**File naming**: Use `.mdx` extension (e.g., `my-post.mdx`)
+
+**Front matter**: Same as regular Hexo posts:
+
+```mdx
+---
+title: Post Title
+date: 2026-01-06
+categories:
+  - Technology
+tags:
+  - hexo
+  - mdx
+---
+
+Your content here...
+```
+
+#### 4. Using MDX Features
+
+**Standard Markdown** - All markdown features work:
+
+```mdx
+# Heading 1
+## Heading 2
+
+**Bold**, *italic*, ~~strikethrough~~
+
+- List item 1
+- List item 2
+
+[Link text](https://example.com)
+```
+
+**Inline JSX** - Add HTML/JSX elements anywhere:
+
+```mdx
+<div className="custom-class" style={{ color: 'blue' }}>
+  Custom styled content
+</div>
+```
+
+**Custom Components** - Define and use React components:
+
+```mdx
+export const Alert = ({ children, type = 'info' }) => (
+  <div style={{ 
+    padding: '15px',
+    backgroundColor: type === 'warning' ? '#fff3cd' : '#d1ecf1',
+    borderRadius: '5px',
+    margin: '20px 0'
+  }}>
+    {children}
+  </div>
+);
+
+<Alert type="warning">
+  This is a custom alert component!
+</Alert>
+```
+
+**Dynamic Content** - Use JavaScript expressions:
+
+```mdx
+<div>
+  {['React', 'Vue', 'Angular'].map(framework => (
+    <p key={framework}>I ❤️ {framework}</p>
+  ))}
+</div>
+```
+
+#### 5. Building and Deploying
+
+Build your site as usual:
+
+```bash
+# Generate static files
+hexo generate
+
+# Deploy (if configured)
+hexo deploy
+```
+
+The MDX files are compiled to static HTML - no JavaScript runtime needed on your site!
+
+## Usage
+
+After installation, you can create `.mdx` files in your `source/_posts` or `source` directory.
+
+### Basic Example
+
+Create a file `source/_posts/hello-mdx.mdx`:
+
+```mdx
+---
+title: Hello MDX
+date: 2026-01-06
+tags:
+  - mdx
+  - react
+---
+
+# Hello MDX!
+
+This is a regular markdown paragraph.
+
+You can use JSX directly:
+
+<div style={{ padding: '20px', backgroundColor: '#f0f0f0' }}>
+  <h2>Custom Component</h2>
+  <p>This is rendered using JSX!</p>
+</div>
+
+And back to markdown...
+
+## Features
+
+- List item 1
+- List item 2
+- List item 3
+```
+
+### Advanced Example
+
+You can use more complex JSX:
+
+```mdx
+---
+title: Advanced MDX
+---
+
+export const Button = ({ children, color = 'blue' }) => (
+  <button style={{ 
+    backgroundColor: color, 
+    color: 'white', 
+    padding: '10px 20px',
+    border: 'none',
+    borderRadius: '5px',
+    cursor: 'pointer'
+  }}>
+    {children}
+  </button>
+);
+
+# Advanced MDX Example
+
+Here's a custom button component:
+
+<Button color="red">Click Me!</Button>
+
+You can use any valid JSX expression:
+
+<div>
+  {['apple', 'banana', 'cherry'].map(fruit => (
+    <p key={fruit}>I love {fruit}s!</p>
+  ))}
+</div>
+```
+
+## Configuration
+
+The plugin works out of the box with no configuration required. However, you can customize MDX compilation options if needed.
+
+### Advanced Configuration
+
+If you need to customize the MDX compiler options, you can create a `hexo-renderer-mdx` configuration in your Hexo `_config.yml`:
+
+```yaml
+# _config.yml
+mdx:
+  # Enable development mode for better error messages
+  development: false
+```
+
+Note: The current version uses sensible defaults optimized for static site generation.
+
+The plugin:
+1. Compiles MDX files to JavaScript functions
+2. Executes them with a React runtime
+3. Renders the result to static HTML
+4. Passes the HTML to Hexo for page generation
+
+## Requirements
+
+- Node.js >= 14.0.0
+- Hexo >= 5.0.0
+
+## Dependencies
+
+This plugin uses:
+- `@mdx-js/mdx` - MDX compiler
+- `react` & `react-dom` - React runtime for server-side rendering
+
+## Notes
+
+- MDX files are compiled to static HTML at build time
+- Interactive React components will not be interactive in the final output (server-side rendering only)
+- For interactive components, consider using a different approach or client-side hydration
+
+## Troubleshooting
+
+### MDX Compilation Errors
+
+If you encounter compilation errors, check:
+- Your JSX syntax is valid
+- All tags are properly closed
+- You're not using unsupported JSX features
+
+### Missing Dependencies
+
+Make sure all peer dependencies are installed:
+
+```bash
+npm install react react-dom @mdx-js/mdx --save
+```
+
+## Publishing
+
+### For Maintainers
+
+This package uses automated publishing to npm via GitHub Actions with **Trusted Publishing** (OIDC).
+
+**To publish a new version:**
+
+1. Update the version in `package.json`:
+   ```bash
+   npm version patch  # or minor, or major
+   ```
+
+2. Push the changes and tags:
+   ```bash
+   git push && git push --tags
+   ```
+
+3. Create a new release on GitHub:
+   - Go to the repository's "Releases" page
+   - Click "Create a new release"
+   - Select the tag you just created
+   - Add release notes
+   - Click "Publish release"
+
+4. The GitHub Action will automatically:
+   - Run tests
+   - Publish to npm with provenance using Trusted Publishing
+   - Make the package publicly available
+
+**First-time setup:**
+
+Before publishing, you need to configure Trusted Publishing on npm:
+
+1. Go to https://www.npmjs.com/package/hexo-renderer-mdx/access
+2. Click "Publishing" → "Trusted Publishers"
+3. Add a new trusted publisher with:
+   - **Provider**: GitHub Actions
+   - **Repository owner**: Bryan0324
+   - **Repository name**: hexo-renderer-mdx
+   - **Workflow file**: `publish.yml`
+   - **Environment name**: (leave empty)
+
+No npm tokens required! Trusted Publishing uses OpenID Connect (OIDC) for secure authentication.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed publishing instructions.
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT
+
+## Related
+
+- [Hexo](https://hexo.io/)
+- [MDX](https://mdxjs.com/)
+- [React](https://reactjs.org/)

package/index.js

@@ -0,0 +1,75 @@
+'use strict';
+
+const { compile } = require('@mdx-js/mdx');
+const { renderToString } = require('react-dom/server');
+const React = require('react');
+
+/**
+ * MDX Renderer for Hexo
+ * 
+ * This renderer allows you to use MDX files in your Hexo blog.
+ * MDX is markdown with JSX support, allowing you to embed React components.
+ */
+
+/**
+ * Render MDX content to HTML
+ * @param {Object} data - The data object containing MDX content
+ * @param {string} data.text - The MDX content to render
+ * @param {string} data.path - The file path (for error reporting)
+ * @returns {Promise<string>} The rendered HTML
+ */
+async function mdxRenderer(data) {
+  const { text, path } = data;
+  
+  try {
+    // Strip YAML front matter if present
+    // Note: Hexo typically strips front matter before passing to renderers,
+    // but we handle it here as a safety measure for edge cases
+    let content = text;
+    const frontMatterRegex = /^---\s*\n([\s\S]*?)\n---\s*\n/;
+    const match = content.match(frontMatterRegex);
+    
+    if (match) {
+      // Remove front matter from content
+      content = content.slice(match[0].length);
+    }
+    
+    // Compile MDX to JavaScript with automatic JSX runtime
+    const compiled = await compile(content, {
+      outputFormat: 'function-body',
+      development: false,
+      jsxImportSource: 'react'
+    });
+
+    // Create a function from the compiled code
+    const code = String(compiled);
+    
+    // The compiled code expects arguments[0] to be the jsx-runtime
+    const jsxRuntime = require('react/jsx-runtime');
+    
+    // Create and execute the MDX module function
+    // Note: Using new Function() here is safe because:
+    // 1. Input comes from MDX files in the user's Hexo project (not untrusted external input)
+    // 2. MDX compilation itself validates and sanitizes the content
+    // 3. This is a build-time operation, not runtime user input
+    const fn = new Function(code);
+    const mdxModule = fn.call(null, jsxRuntime);
+    
+    // The result has a default export which is the MDX component
+    const MDXContent = mdxModule.default;
+    
+    // Render the component to static HTML
+    const html = renderToString(
+      React.createElement(MDXContent, {})
+    );
+    
+    return html;
+  } catch (err) {
+    throw new Error(`MDX compilation failed for ${path}: ${err.message}`);
+  }
+}
+
+/**
+ * Register the MDX renderer with Hexo
+ */
+hexo.extend.renderer.register('mdx', 'html', mdxRenderer, true);

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "hexo-renderer-mdx",
+  "version": "1.0.0",
+  "description": "MDX renderer plugin for Hexo with React component support",
+  "main": "index.js",
+  "scripts": {
+    "test": "node test.js && node test-advanced.js"
+  },
+  "keywords": [
+    "hexo",
+    "renderer",
+    "mdx",
+    "markdown",
+    "jsx",
+    "react"
+  ],
+  "author": "Bryan0324",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Bryan0324/hexo-renderer-mdx.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Bryan0324/hexo-renderer-mdx/issues"
+  },
+  "homepage": "https://github.com/Bryan0324/hexo-renderer-mdx#readme",
+  "dependencies": {
+    "@mdx-js/mdx": "^3.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependencies": {
+    "hexo": ">=5.0.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}