Imported from jotafeldmann/google-docs-theme (
AGENTS.md). Install upstream withnpx skills add jotafeldmann/google-docs-theme. Copyright stays with the author.
You're right! AGENTS.md is a conventions file meant to guide AI agents (like me) on how to work with this codebase — what the project does, how it's structured, rules to follow, and how to make changes safely. Here's the proper version:
# 🤖 AGENTS.md
This file provides instructions and context for AI agents working on the **google-docs-theme** project.
---
## Project Overview
**google-docs-theme** is a Google Apps Script add-on bound to a Google Docs document. It adds a sidebar UI that lets users toggle the document's page background between light (white) and dark (black) mode, including text color adjustment.
---
## Project Structure
```
google-docs-theme/
├── main.gs # Server-side Apps Script logic (menu, sidebar, theme toggle)
├── sidebar.html # Client-side sidebar UI (HTML + CSS + JS)
├── preview/ # Screenshots used in README documentation
└── README.md # Project documentation
```
---
## Code Architecture
### `main.gs` (server-side)
Contains all Google Apps Script server-side functions:
- `onOpen()` — installs the **🎨 Theme** menu in the Google Docs toolbar when the document opens. This is a simple trigger.
- `openSidebar()` — loads and displays `sidebar.html` as a sidebar panel (260px wide).
- `setBackground(dark)` — sets the document body background and text foreground color. Accepts a boolean: `true` for dark, `false` for light.
- `getCurrentBackground()` — reads the current document body background color and returns `true` if it is dark (i.e., not white and not null).
### `sidebar.html` (client-side)
A self-contained HTML file rendered inside the Google Docs sidebar:
- Uses `google.script.run` to call server-side functions (`setBackground`, `getCurrentBackground`).
- Contains all CSS inline (no external dependencies).
- Implements a toggle switch UI that reflects and controls the current document theme.
- Applies a `.dark` class to `<body>` to also theme the sidebar panel itself.
---
## Key Conventions
- **File names are lowercase** — `main.gs` and `sidebar.html`. Do not capitalize them.
- The HTML file is referenced in code as `'sidebar'` (without extension): `HtmlService.createHtmlOutputFromFile('sidebar')`. This string must always match the file name exactly.
- **No external libraries or CDNs** — the sidebar is fully self-contained.
- Colors used: `#000000` (dark background), `#FFFFFF` (light background/text), reversed for each mode.
- The script is **document-bound** (not a standalone script). It operates only on the active document.
---
## How to Make Changes
- To change theme colors, update the hex values in `setBackground()` inside `main.gs` and adjust the CSS in `sidebar.html` accordingly.
- To add new themes beyond light/dark, extend `setBackground()` to accept a string or enum instead of a boolean, and update the sidebar toggle UI to support multiple options.
- To change the sidebar width, update `.setWidth(260)` in `openSidebar()`.
- To rename any `.html` file, always update the corresponding `createHtmlOutputFromFile('name')` call in `main.gs` to match exactly, including case.
---
## AI Agent Notes
This project was developed with assistance from **Claude (Anthropic)**, which was used to write the initial code, generate documentation, rename files, and apply edits directly in the Google Apps Script editor via browser automation.
When working on this codebase, agents should:
- Always keep `main.gs` and `sidebar.html` in sync (especially the file reference string).
- Avoid adding external dependencies — keep the sidebar self-contained.
- Test `onOpen()` manually after any changes to the menu structure.
- Not rename files without updating all internal references.