# Repository Guidelines

## Project Structure & Module Organization

SoMarkDown is an ES module JavaScript library built on markdown-it for browser and Node.js rendering.

- `src/core/` contains the renderer and default configuration; `src/index.js` exposes the public API.
- `src/plugins/` contains feature modules such as `caption`, `katex`, and `html-table`; `src/utils/` contains shared helpers.
- `styles/` contains SCSS base styles, plugin partials, and themes.
- `test/unit/` contains Jest tests. `example/browser/` and `example/node/` provide runnable demonstrations.
- `docs/Syntax.md` documents syntax; `docs/assets/` stores documentation images. `dist/` contains generated, Git-ignored bundles.

## Build, Test, and Development Commands

- `npm ci`: install dependencies from the committed lockfile.
- `npm run build`: use Rollup to generate ESM, UMD, minified UMD, CSS, and source maps in `dist/`.
- `npm test`: run Jest with Node's experimental VM module support.
- `npm test -- --runInBand test/unit/caption.test.js`: run a focused test file.
- `npm run lint`: check `src/` using ESLint's recommended rules.
- After building, run `node example/node/index.js` or open `example/browser/index.html` to inspect rendering locally.

## Coding Style & Naming Conventions

Follow surrounding formatting: source and SCSS generally use four-space indentation; Rollup configuration uses two. Use ES module imports with explicit `.js` extensions, single-quoted JavaScript strings, and semicolons. Use camelCase for functions and variables, PascalCase for classes, and kebab-case plugin directories. Export plugins through `src/plugins/index.js`. ESLint is configured in `.eslintrc.cjs`; no dedicated formatter is configured.

Preserve separate Node and browser implementations in `dom.js`/`dom.browser.js` and the HTML-table plugin, including package and Rollup mappings.

## Testing Guidelines

Jest uses the Node environment and Babel transformation. Name tests `test/unit/<feature>.test.js`; group behavior with `describe` and assert rendered HTML. Add regression cases for parser fixes, including relevant edge cases. No coverage threshold is configured. For small changes, run directly relevant tests; build and inspect the browser example when changing styles or bundling.

## Commit & Pull Request Guidelines

- Do not commit or push changes unless the user explicitly requests it.
- Never include `AGENTS.md` in staging, commits, or pushes; keep it local to this repository.

History uses short descriptive subjects such as `Add hr style` and version-only release commits; Conventional Commits are not required. Keep commits focused. Pull requests should explain the behavior change, link relevant issues, and list validation commands and results. Include before/after screenshots for rendering changes and update both READMEs or syntax documentation when applicable.