diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..f390f1952a --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# 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: + * 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. + +## 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..fb47090216 --- /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`. + +## Core Technologies +* **Language:** JavaScript (Node.js) +* **Libraries:** `commander` (CLI), `winston` (Logging). + +## Key Files +* `index.js`: Main entry point. +* `test/functional/`: Functional tests (crucial for CLI verification). + +## 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`. + +## 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..962cf38333 --- /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. + +## 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..0484396fc7 --- /dev/null +++ b/packages/core/AGENTS.md @@ -0,0 +1,28 @@ +# AGENTS.MD: Core Package Guide + +## Package Overview +The `@markbind/core` package contains the core logic for processing Markdown, plugins, and generating the final HTML output. + +## Core Technologies +* **Language:** TypeScript +* **Libraries:** `markdown-it`, `nunjucks`, `fs-extra`. + +## Key Files +* `src/index.ts`: Main entry point. +* `src/plugins/`: Custom MarkBind plugins. + +## 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. + +## 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..4ff6768fee --- /dev/null +++ b/packages/vue-components/AGENTS.md @@ -0,0 +1,28 @@ +# AGENTS.MD: Vue Components Package Guide + +## Package Overview +The `@markbind/vue-components` package contains the Vue 3 component library utilized by MarkBind sites. + +## Core Technologies +* **Framework:** Vue 3 +* **Style:** Bootstrap / Scoped CSS + +## Key Files +* `src/*.vue`: Vue components. +* `src/__tests__/`: Component tests. + +## 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. + +## 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.