Skip to content

Commit 122f67d

Browse files
ayoniousayonious
committed
chore: add agents
1 parent 2bae552 commit 122f67d

1 file changed

Lines changed: 160 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
# AGENTS.md
2+
3+
This guide is for future agents and maintainers working in this documentation repository. It summarizes how the Docusaurus site is organized, how documentation changes should be made, and which checks matter before handing work back.
4+
5+
## Project Overview
6+
7+
`console-table-docu` is the Docusaurus documentation site for the `console-table-printer` package. The site documents library features, CLI usage, API reference pages, screenshots, and examples. It is deployed to Netlify and built from Markdown docs plus a small React homepage.
8+
9+
The sibling implementation repos are usually checked out next to this repo:
10+
11+
- `../console-table-printer`: source of truth for public exports, TypeScript option types, tested rendering behavior, and library README examples.
12+
- `../table-printer-cli`: source of truth for the `ctp` command, CLI flags, package metadata, README examples, and CLI screenshots.
13+
14+
## Repository Map
15+
16+
- `docs/`: user-facing documentation pages.
17+
- `docs/doc-*.md`: feature and workflow guides.
18+
- `docs/api/`: API reference pages for functions, table methods, and configuration.
19+
- `sidebars.js`: Docusaurus sidebar structure. New docs pages must be added here to be discoverable.
20+
- `docusaurus.config.js`: site metadata, navbar/footer links, docs plugin config, edit URL, and custom CSS wiring.
21+
- `src/pages/index.tsx`: homepage entry point.
22+
- `src/components/`: homepage components.
23+
- `src/css/`: custom theme CSS and CSS variables.
24+
- `src/utils/sources.tsx`: homepage feature-card content.
25+
- `src/__mocks__/`: Jest mocks for Docusaurus, theme, CSS, and static assets.
26+
- `src/test-utils/`: React Testing Library helpers.
27+
- `cypress/e2e/`: integration tests for navigation, links, pages, images, and URLs.
28+
- `static/img/`: favicon, logos, homepage images, and documentation screenshots.
29+
- `examples.ts`: local example script for console-table-printer scenarios. Keep examples consistent with docs when editing it.
30+
- `netlify.toml`: Netlify build settings. The build command is `yarn build` and the publish directory is `build/`.
31+
32+
## Development Commands
33+
34+
Use Yarn for this repository.
35+
36+
```bash
37+
yarn
38+
yarn start
39+
yarn build
40+
yarn test
41+
yarn test:coverage
42+
yarn test-integration
43+
```
44+
45+
Useful targeted checks:
46+
47+
```bash
48+
yarn test src/pages/__tests__/index.test.tsx
49+
yarn test src/components/Sources/__tests__/Sources.test.tsx
50+
yarn cy:run
51+
```
52+
53+
Notes:
54+
55+
- `yarn start` runs Docusaurus locally, normally at `http://localhost:3000`.
56+
- `yarn build` catches Docusaurus build errors, broken imports, malformed Markdown/MDX, and missing static assets.
57+
- `yarn test` runs Jest in `jsdom` using `jest.config.js`.
58+
- `yarn test-integration` starts the Docusaurus dev server and runs Cypress against `http://localhost:3000`.
59+
- Netlify currently uses Node `22.16.0` from `netlify.toml`.
60+
61+
## Documentation Workflow
62+
63+
When adding or changing docs:
64+
65+
1. Start from the implementation source of truth. For library behavior, use `../console-table-printer`, especially `index.ts`, `src/models/external-table.ts`, and feature tests under `test/features/`. For CLI behavior, use `../table-printer-cli`, especially `index.ts`, `src/service.ts`, `package.json`, `README.md`, and tests under `test/readmeExamples/`.
66+
2. Decide whether the behavior deserves a standalone guide page, an API reference update, or both.
67+
3. Add or edit Markdown under `docs/`.
68+
4. If adding a new page, add its document id to `sidebars.js`.
69+
5. If the page has screenshots, store them under `static/img/examples/<doc-id>/` and reference them through `useBaseUrl`.
70+
6. Update Cypress page/link/url expectations when the sidebar label, page title, URL, required headings, or screenshot counts change.
71+
7. Keep examples runnable and aligned with the current package API.
72+
73+
Prefer practical, task-oriented docs. A feature page should show the smallest useful example first, then one or two realistic variations. API reference pages should be complete and precise about signatures, options, return values, defaults, and edge cases.
74+
75+
## Feature Declaration Checklist
76+
77+
A user-facing feature is not fully declared until the relevant documentation surface exists. Before considering a feature documented, check for:
78+
79+
- A discoverable guide page in `docs/` when the behavior is more than a small option.
80+
- `docs/api/core-functions.md` updates for top-level helpers such as `printTable` and `renderTable`.
81+
- `docs/api/table-methods.md` updates for `Table` instance methods.
82+
- `docs/api/configuration.md` updates for constructor options, column options, row options, callbacks, enums, and supported value types.
83+
- `docs/doc-cli-install-quick-start.md` and `docs/doc-cli-brew.md` updates when `ctp` install steps, flags, stdin/input behavior, table-options examples, help output, or screenshots change.
84+
- A `sidebars.js` entry for every new guide page.
85+
- Cypress updates in `cypress/e2e/link_tests.cy.ts`, `page_tests.cy.ts`, and `url_tests.cy.ts` when navigation, labels, URLs, or required headings change.
86+
- Screenshots for visual output changes, with stable paths under `static/img/examples/`.
87+
- Cross-links from nearby topics so users can find related behavior.
88+
89+
Common gaps to watch for:
90+
91+
- Public exports in the library that are absent from API docs.
92+
- Public constructor options in `ComplexOptions` that appear only in a broad example.
93+
- Feature tests in `../console-table-printer/test/features/` that have no dedicated guide or API section.
94+
- CLI flags or README examples in `../table-printer-cli` that are absent from CLI docs.
95+
- Docs that describe the implementation inaccurately, such as saying an option disables border characters when it only disables ANSI colors.
96+
97+
## Page And Sidebar Conventions
98+
99+
Each docs page should have frontmatter:
100+
101+
```md
102+
---
103+
id: doc-example-id
104+
title: Human Page Title
105+
sidebar_label: Sidebar Label
106+
---
107+
```
108+
109+
Use `doc-*` ids for feature guides and place API reference docs under `docs/api/`. Keep sidebar labels short and stable because Cypress tests assert them directly.
110+
111+
For pages with images:
112+
113+
```md
114+
import useBaseUrl from '@docusaurus/useBaseUrl';
115+
116+
<img alt="Screenshot" src={useBaseUrl('img/examples/doc-example-id/screenshot.png')}/>
117+
```
118+
119+
Keep screenshot filenames descriptive enough to understand the scenario from the path. If a screenshot changes because output intentionally changed, update the file and verify image-loading Cypress tests still pass.
120+
121+
## Testing Guidance
122+
123+
Choose checks based on the change:
124+
125+
- Markdown-only edits to an existing page: usually run `yarn build` when imports, links, images, or MDX syntax changed.
126+
- New docs page or sidebar movement: run `yarn build` and update/run the relevant Cypress tests.
127+
- Homepage/component changes: run `yarn test` and consider `yarn build`.
128+
- Link, navbar, footer, sidebar, image, or URL changes: run `yarn test-integration` or the relevant Cypress spec through `yarn cy:run`.
129+
- Config or deployment changes: run `yarn build` and inspect `netlify.toml`/`docusaurus.config.js` carefully.
130+
131+
Cypress tests intentionally duplicate page titles, sidebar labels, URLs, and required headings. When editing those strings in docs or config, update the corresponding test data in `cypress/e2e/` in the same change.
132+
133+
## Style And Content
134+
135+
- Keep examples concrete and aligned with real `console-table-printer` APIs.
136+
- Prefer JavaScript or TypeScript examples that users can paste with minimal surrounding code.
137+
- Use consistent import style: `import { Table, printTable, renderTable } from 'console-table-printer';` as appropriate.
138+
- Do not document behavior only in screenshots; include a short explanation and code.
139+
- Avoid inventing options or aliases that are not present in the library.
140+
- Keep page titles and headings descriptive because they are used by Cypress tests and by users scanning the sidebar.
141+
- Use ASCII in new text unless the page specifically demonstrates console borders, emoji, or non-ASCII output.
142+
143+
## Before Finishing A Change
144+
145+
For small documentation edits, inspect the Markdown and run no command only when there are no imports, links, images, or sidebar changes.
146+
147+
For new pages, sidebars, links, images, homepage changes, or API reference rewrites, usually run:
148+
149+
```bash
150+
yarn build
151+
yarn test
152+
```
153+
154+
For navigation-sensitive changes, also run:
155+
156+
```bash
157+
yarn test-integration
158+
```
159+
160+
If tests are not run, say so in the handoff and identify the highest-risk unchecked area.

0 commit comments

Comments
 (0)