From 725a590a03c67329d6082310e864ba3312e56904 Mon Sep 17 00:00:00 2001 From: gerteck Date: Sat, 31 Jan 2026 19:06:41 +0800 Subject: [PATCH 1/3] Add `AGENTS.md` files to provide guidelines for project and packages --- AGENTS.md | 85 +++++++++++++++++++++++++++++++ packages/cli/AGENTS.md | 26 ++++++++++ packages/core-web/AGENTS.md | 23 +++++++++ packages/core/AGENTS.md | 28 ++++++++++ packages/vue-components/AGENTS.md | 28 ++++++++++ 5 files changed, 190 insertions(+) create mode 100644 AGENTS.md create mode 100644 packages/cli/AGENTS.md create mode 100644 packages/core-web/AGENTS.md create mode 100644 packages/core/AGENTS.md create mode 100644 packages/vue-components/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..3f95324159 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,85 @@ +# AGENTS.MD: AI Collaboration Guide + +## Project Overview & Purpose + +* MarkBind is a static site generator optimized for content-heavy instructional websites (e.g., courses, tutorials, documentation). It converts Markdown-like syntax into rich, interactive HTML websites. +* Business Domain: Documentation, Education, Static Site Generation (SSG). + +## Core Technologies & Stack + +* Languages: + * TypeScript (Backend/Core logic, `packages/core`) + * JavaScript (Legacy scripts, CLI, Webpack configs) + * Vue.js 3 (Frontend components, `packages/vue-components`, `packages/core-web`) +* Frameworks & Runtimes: + * Node.js (Runtime) + * Vue 3 (Frontend Framework) + * Jest (Testing) +* Key Libraries/Dependencies: + * `markdown-it` (Markdown parsing) + * `nunjucks` (Templating) + * `commander` (CLI interface) + * `webpack` (Asset bundling) +* Package Manager(s): + * `npm` (Workspaces enabled) + * `lerna` (Monorepo orchestration) + +## Architectural Patterns + +* Overall Architecture: Monorepo structure managed by Lerna. Separates concerns into: + * CLI (`packages/cli`): Command-line interface and orchestration. + * Core (`packages/core`): Main logic for parsing and generating sites. + * Core-Web (`packages/core-web`): Client-side assets and build configuration. + * Vue Components (`packages/vue-components`): UI library for the generated sites. +* Directory Structure Philosophy: + * `packages/`: Contains all monorepo packages. + * `docs/`: Documentation site content (dogfooding MarkBind). + * `scripts/`: Maintainance and utility scripts. + +## Coding Conventions & Style Guide + +* Formatting: + * Indentation: 2 spaces. + * Style: Follows `airbnb-base` and `airbnb-typescript`. + * Enforced via ESLint (`.eslintrc.js`). +* Naming Conventions: + * Variables/Functions: camelCase (`processMarkdown`). + * Classes: PascalCase (`SiteDeployManager`). + * Files: kebab-case preferred for new files, though consistency with existing structure is paramount. + +## Key Files & Entrypoints + +* CLI Entry: `packages/cli/index.js` +* Core Entry: `packages/core/index.js` +* Monorepo Config: `lerna.json` +* Lint Config: `.eslintrc.js` + +## Development & Testing Workflow + +* Local Development Environment: + * Backend (Core): Run `npm run dev` in the root to watch/recompile TypeScript. Otherwise, run `npm run build:backend` to compile TypeScript. + * Frontend: Run `markbind serve -d` to enable hot reloading of client assets. + * Troubleshooting: Run `npm run clean` to remove compiled artifacts if you encounter "orphaned file" issues (e.g., after renaming `.ts` files). + * Warning: Do NOT build full release bundles (`npm run build:web`) manually unless releasing. +* Testing: + * Run `npm test` for all tests. + * Localized Testing: Run tests in specific package directories (`packages/core`, etc.) for efficiency. +* CI/CD Process: GitHub Actions (`.github/workflows`) handle testing and linting on PRs. + +## Specific Instructions for AI Collaboration + +* Contribution: + * Follow the "Do" and "Don't" lists in package-specific `AGENTS.md` files. + * Ensure small diffs and meaningful commit messages. +* Security: + * Do not hardcode secrets. + * Validate inputs in CLI and Core logic. +* Dependencies: + * Use `npm` workspaces. + * Do not add heavy dependencies without strong justification. + +See each package's `AGENTS.md` for specific guidelines: +* [CLI](packages/cli/AGENTS.md) +* [Core](packages/core/AGENTS.md) +* [Core Web](packages/core-web/AGENTS.md) +* [Vue Components](packages/vue-components/AGENTS.md) diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md new file mode 100644 index 0000000000..40597f104b --- /dev/null +++ b/packages/cli/AGENTS.md @@ -0,0 +1,26 @@ +# AGENTS.MD: CLI Package Guide + +The `markbind-cli` package handles command-line operations, argument parsing, and orchestrates the build process by invoking `@markbind/core`. + +## 2. Core Technologies +* **Language:** JavaScript (Node.js) +* **Libraries:** `commander` (CLI), `winston` (Logging). + +## 3. Key Files +* `index.js`: Main entry point. +* `test/functional/`: Functional tests (crucial for CLI verification). + +## 4. Development Workflow +* **Testing:** + * `npm test`: Runs unit and functional tests. + * `npm run updatetest`: Updates functional test snapshots. +* **Dependencies:** Relies on `@markbind/core` and `@markbind/core-web`. + +## 5. Coding & Contribution Rules +### Do +- Use `commander` for new CLI commands/options. +- Ensure `index.js` remains the main entry point. +- Use `winston` for logging. + +### Don't +- Do not put core site generation logic here; delegate to `@markbind/core`. diff --git a/packages/core-web/AGENTS.md b/packages/core-web/AGENTS.md new file mode 100644 index 0000000000..9f99267a88 --- /dev/null +++ b/packages/core-web/AGENTS.md @@ -0,0 +1,23 @@ +# AGENTS.MD: Core Web Package Guide + +## Package Overview +The `@markbind/core-web` package manages client-side assets (JS/CSS) and the webpack build process. + +## Core Technologies +* **Language:** JavaScript, Vue +* **Build Tool:** Webpack (with `babel`, `vue-loader`). + +## Key Files +* `webpack.build.js`: Webpack configuration. +* `src/`: Client-side JavaScript/Vue entry points. + +## Development Workflow +* **Editing Frontend Features:** + * **Recommended**: Run `markbind serve -d` to compile bundles and enable hot reloading. + * **Release Only**: `npm run build:client` / `npm run build:server`. + * **Do NOT** build full bundles manually during development. + +## 5. Coding & Contribution Rules +### Do +- Use Webpack for bundling assets. +- Ensure `babel` transforms are correctly configured for target browsers. diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md new file mode 100644 index 0000000000..9d1b79d33c --- /dev/null +++ b/packages/core/AGENTS.md @@ -0,0 +1,28 @@ +# AGENTS.MD: Core Package Guide + +## 1. Package Overview +The `@markbind/core` package contains the core logic for processing Markdown, plugins, and generating the final HTML output. + +## 2. Core Technologies +* **Language:** TypeScript +* **Libraries:** `markdown-it`, `nunjucks`, `fs-extra`. + +## 3. Key Files +* `src/index.ts`: Main entry point. +* `src/plugins/`: Custom MarkBind plugins. + +## 4. Development Workflow +* **Compilation:** + * `npm run dev` (in Root): Useful for watching changes. + * `npm run compile`: Manual TypeScript compilation. +* **Testing:** + * `npm run test`: Runs Jest tests. + +## 5. Coding & Contribution Rules +### Do +- Use TypeScript for all new logic. +- Implement `markdown-it` plugins for new syntax features. +- Keep processing logic separate from UI generation where possible. + +### Don't +- Do not mix pure markdown processing with file I/O if avoidable (make logic testable). diff --git a/packages/vue-components/AGENTS.md b/packages/vue-components/AGENTS.md new file mode 100644 index 0000000000..9961ba203d --- /dev/null +++ b/packages/vue-components/AGENTS.md @@ -0,0 +1,28 @@ +# GEMINI.MD: Vue Components Package Guide + +## 1. Package Overview +The `@markbind/vue-components` package contains the Vue 3 component library utilized by MarkBind sites. + +## 2. Core Technologies +* **Framework:** Vue 3 +* **Style:** Bootstrap / Scoped CSS + +## 3. Key Files +* `src/*.vue`: Vue components. +* `src/__tests__/`: Component tests. + +## 4. Development Workflow +* **Testing:** + * `npm test`: Run component tests. + * `npm run updatetest`: Snapshot updates. + * Use `markbind serve -d` in a test site to visually verify components. + +## 5. Coding & Contribution Rules +### Do +- **Vue Options API**: Maintain consistency with existing components (e.g., `Box.vue`). +- **Scoped CSS**: Prevent style leakage. +- **Props**: Define clear props with types and defaults. + +### Don't +- **Composition API**: Avoid unless explicitly approved. +- **Hardcoding**: Use props or bootstrap tokens for colors/styles. From c3d77991738348d9a310bfb4e89118ac58a33de7 Mon Sep 17 00:00:00 2001 From: gerteck Date: Sat, 31 Jan 2026 19:11:06 +0800 Subject: [PATCH 2/3] Update wording --- packages/cli/AGENTS.md | 8 ++++---- packages/core-web/AGENTS.md | 2 +- packages/core/AGENTS.md | 10 +++++----- packages/vue-components/AGENTS.md | 12 ++++++------ 4 files changed, 16 insertions(+), 16 deletions(-) diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md index 40597f104b..fb47090216 100644 --- a/packages/cli/AGENTS.md +++ b/packages/cli/AGENTS.md @@ -2,21 +2,21 @@ The `markbind-cli` package handles command-line operations, argument parsing, and orchestrates the build process by invoking `@markbind/core`. -## 2. Core Technologies +## Core Technologies * **Language:** JavaScript (Node.js) * **Libraries:** `commander` (CLI), `winston` (Logging). -## 3. Key Files +## Key Files * `index.js`: Main entry point. * `test/functional/`: Functional tests (crucial for CLI verification). -## 4. Development Workflow +## Development Workflow * **Testing:** * `npm test`: Runs unit and functional tests. * `npm run updatetest`: Updates functional test snapshots. * **Dependencies:** Relies on `@markbind/core` and `@markbind/core-web`. -## 5. Coding & Contribution Rules +## Coding & Contribution Rules ### Do - Use `commander` for new CLI commands/options. - Ensure `index.js` remains the main entry point. diff --git a/packages/core-web/AGENTS.md b/packages/core-web/AGENTS.md index 9f99267a88..962cf38333 100644 --- a/packages/core-web/AGENTS.md +++ b/packages/core-web/AGENTS.md @@ -17,7 +17,7 @@ The `@markbind/core-web` package manages client-side assets (JS/CSS) and the web * **Release Only**: `npm run build:client` / `npm run build:server`. * **Do NOT** build full bundles manually during development. -## 5. Coding & Contribution Rules +## Coding & Contribution Rules ### Do - Use Webpack for bundling assets. - Ensure `babel` transforms are correctly configured for target browsers. diff --git a/packages/core/AGENTS.md b/packages/core/AGENTS.md index 9d1b79d33c..0484396fc7 100644 --- a/packages/core/AGENTS.md +++ b/packages/core/AGENTS.md @@ -1,24 +1,24 @@ # AGENTS.MD: Core Package Guide -## 1. Package Overview +## Package Overview The `@markbind/core` package contains the core logic for processing Markdown, plugins, and generating the final HTML output. -## 2. Core Technologies +## Core Technologies * **Language:** TypeScript * **Libraries:** `markdown-it`, `nunjucks`, `fs-extra`. -## 3. Key Files +## Key Files * `src/index.ts`: Main entry point. * `src/plugins/`: Custom MarkBind plugins. -## 4. Development Workflow +## Development Workflow * **Compilation:** * `npm run dev` (in Root): Useful for watching changes. * `npm run compile`: Manual TypeScript compilation. * **Testing:** * `npm run test`: Runs Jest tests. -## 5. Coding & Contribution Rules +## Coding & Contribution Rules ### Do - Use TypeScript for all new logic. - Implement `markdown-it` plugins for new syntax features. diff --git a/packages/vue-components/AGENTS.md b/packages/vue-components/AGENTS.md index 9961ba203d..4ff6768fee 100644 --- a/packages/vue-components/AGENTS.md +++ b/packages/vue-components/AGENTS.md @@ -1,23 +1,23 @@ -# GEMINI.MD: Vue Components Package Guide +# AGENTS.MD: Vue Components Package Guide -## 1. Package Overview +## Package Overview The `@markbind/vue-components` package contains the Vue 3 component library utilized by MarkBind sites. -## 2. Core Technologies +## Core Technologies * **Framework:** Vue 3 * **Style:** Bootstrap / Scoped CSS -## 3. Key Files +## Key Files * `src/*.vue`: Vue components. * `src/__tests__/`: Component tests. -## 4. Development Workflow +## Development Workflow * **Testing:** * `npm test`: Run component tests. * `npm run updatetest`: Snapshot updates. * Use `markbind serve -d` in a test site to visually verify components. -## 5. Coding & Contribution Rules +## Coding & Contribution Rules ### Do - **Vue Options API**: Maintain consistency with existing components (e.g., `Box.vue`). - **Scoped CSS**: Prevent style leakage. From 9897a6fe477cef66c5e1dd8cba31dc5e62bd8d5c Mon Sep 17 00:00:00 2001 From: gerteck Date: Mon, 2 Feb 2026 23:13:09 +0800 Subject: [PATCH 3/3] Fix nits --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 3f95324159..f390f1952a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -57,12 +57,14 @@ ## Development & Testing Workflow * Local Development Environment: + * Initial Setup: Run `npm run setup` to install dependencies, clean artifacts, and bootstrap the monorepo. * Backend (Core): Run `npm run dev` in the root to watch/recompile TypeScript. Otherwise, run `npm run build:backend` to compile TypeScript. * Frontend: Run `markbind serve -d` to enable hot reloading of client assets. * Troubleshooting: Run `npm run clean` to remove compiled artifacts if you encounter "orphaned file" issues (e.g., after renaming `.ts` files). * Warning: Do NOT build full release bundles (`npm run build:web`) manually unless releasing. * Testing: * Run `npm test` for all tests. + * Run `npm run updatetest` to update test snapshots. * Localized Testing: Run tests in specific package directories (`packages/core`, etc.) for efficiency. * CI/CD Process: GitHub Actions (`.github/workflows`) handle testing and linting on PRs.