Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (95 loc) · 7.06 KB

AGENTS.md

File metadata and controls

135 lines (95 loc) · 7.06 KB
Raw

AGENTS.md — WaveMaker Docs

Always-on rules for any agent working in this repo. Specialized workflows live in ai-skills/ — load the matching skill for those. This file covers guardrails only.

Repo

WaveMaker public documentation. Docusaurus 3.9.2, MDX-first, Node ≥ 20. Deploys to docs.wavemaker.ai.

Hard rules

  • Never edit build/, .docusaurus/, or node_modules/.
  • Never edit scripts/metrics.json — it is regenerated by npm run gen-metrics.
  • Never bypass hooks with --no-verify. Fix the lint/build error instead.
  • Never invent entries in data/author/authors.yml or any tags.yml. If a referenced key is missing, stop and ask the user.
  • Never add an <h1> to a doc, blog, or announcement body. Titles come from frontmatter.
  • Never place doc-, announcement-, or post-specific assets under static/img/. Co-locate them next to their content (see Asset co-location in File conventions).

Validation gate

Before declaring any content change done, run from the repo root:

npm run lint     # eslint + mdxlint --frail
npm run build    # enforces onBrokenLinks/Images: throw

Both must pass. The build is the source of truth for link and image correctness — lint alone is not sufficient.

File conventions

  • Prefer .mdx over .md for new pages.
  • Filenames are kebab-case. Blog and feature-announcement files are prefixed YYYY-MM-DD-.
  • Docs require frontmatter: last_update: { author: "Name" }.
  • Blogs and announcements use authors: [key] (array). Keys come from data/author/authors.yml, not display names.
  • Body headings start at ##.
  • Cross-plugin links use URL paths, not filesystem-relative MDX paths. Docs-style relative links (../../section/page) only resolve between files under docs/. From a blog or feature announcement, link to a doc as /docs/<section>/<page>.
  • Any file prefixed YYYY-MM-DD- (all blog posts and feature announcements) publishes at /<route>/YYYY/MM/DD/<slug>. Link to it with the date segments — never /<route>/<slug>.
  • In .mdx files, HTML comments (<!-- ... -->) are not valid syntax and fail the build. Use the JSX-expression form {/* ... */} for comments and for the blog truncate marker ({/* truncate */}).
  • MDX components registered in src/theme/MDXComponents/index.js (e.g., AcademyCard, VideoCard, Pill, PillGroup, Accordian, TabsWrapper) are globally available in any .mdx file. Do not import them — it causes redeclaration errors.
  • Angle-bracket placeholders (<Your text here>) are unsafe in MDX bodies — MDX parses them as JSX elements and fails on the next punctuation. In templates and examples, use plain-text placeholders or wrap JSX examples inside {/* ... */} comments.

Asset co-location

Never put content-specific assets under static/img/ — that directory is for globally shared assets only (e.g., favicons, site-wide logos). Everything else is co-located next to its content.

Images and GIFs

Place images and GIFs in an assets/img/ subdirectory next to the .md / .mdx file. This applies across all content types — docs pages, blog posts, and feature announcements alike.

Reference them with a relative path using standard Markdown image syntax:

![Descriptive alt text](./assets/img/filename.png)
![Auto Layout demo](./assets/img/auto-layout-demo.gif)

Videos

Place videos in assets/vids/ next to the post:

<video controls width="100%" muted playsInline poster={require('./assets/vids/poster.jpg').default}>
  <source src={require('./assets/vids/demo.mp4').default} type="video/mp4" />
</video>

Shared assets — nearest common ancestor

If the same asset is used in more than one file, place it in the assets/img/ directory of their nearest common ancestor. For example, if section/page-a.mdx and section/page-b.mdx both use the same image, it goes in section/assets/img/, and both files reference it with ./assets/img/filename.png.

Alt text

Required on every image. Describe what the image shows — not the surrounding heading or section title.

Where things live

docs/<section>/                          → documentation pages (sidebar-registered)
docs/release-notes/                      → versioned release notes
blogs/blog/                              → engineering blog posts          (/blog)
blogs/feature-announcements/             → product feature announcements   (/feature-announcements)
<content-dir>/assets/img/               → co-located images and GIFs (docs and blogs)
<content-dir>/assets/vids/     → co-located videos (feature announcements)
static/img/                              → globally shared assets (/img/... in links)
data/author/authors.yml             → shared author registry
sidebar/sidebars.js                 → aggregator; do not add logic here
sidebar/sidebars/*.js               → per-section sidebar configs
scripts/doc-manager.mjs             → interactive CLI (npm run manage-docs)
ai-skills/                          → agent skills for common workflows

Sidebar editing

Do not hand-edit sidebar/sidebars/*.js with regex or free-form writes. Prefer, in order:

  1. npm run manage-docs — interactive CLI that handles sidebar insertion, naming variants, and rollback.
  2. Importing helpers from scripts/doc-manager.mjs (insertItemIntoSidebar, getDocTemplate, getNameVariants, parseSidebarContent).

Direct edits are acceptable only for small, obvious changes (reordering a known entry, fixing a label typo).

Writing style

Full style guide is in CONTRIBUTING.md. Short version:

  • Active voice, present tense, sentence case headings.
  • Be direct. "Configure the settings," not "You might want to configure the settings."
  • Use admonitions (:::tip, :::note, :::warning, :::danger) sparingly.
  • Every image has alt text.
  • Internal links use relative MDX paths; prefer them over external links when the content is on-site.

Commands

npm start             # dev server
npm run build         # production build (full link/image check)
npm run lint          # eslint + mdxlint --frail
npm run manage-docs   # interactive: new sidebar / category / doc
npm run gen-metrics   # regenerate scripts/metrics.json

Skills

For specific workflows, load the matching skill under ai-skills/ rather than improvising:

  • wm-ai-release-notes — add or edit entries in a versioned release notes file under docs/release-notes/.
  • wm-feature-announcements — new post under blogs/feature-announcements/.
  • wm-ai-create-guide — create a how-to or tutorial page under docs/guide/.
  • wm-ai-documentation — write, update, move, or delete a core reference or conceptual doc under docs/<section>/... (interactive: outlines first, drafts section by section, handles assets, links, and sidebar wiring).

Commits & PRs

  • Branches: feature/<short-desc> or docs/<short-desc>.
  • Do not commit build/, .docusaurus/, or regenerated scripts/metrics.json.
  • Husky runs lint-staged on commit. If it fails, fix the underlying issue — do not skip the hook.
  • PR titles are descriptive ("Add authentication guide for REST APIs"), not generic ("Update docs").