Technical Documentation
Overview
Build technical documentation as a source HTML file plus an exported PDF. Favor a calm, documentation-native visual language: readable type, restrained color, thin borders, dotted separators, status dots, clear tables, and code blocks that feel like a developer artifact rather than a marketing deck.
Workflow
- Clarify the document purpose, audience, source facts, and final format. If source code or configs exist locally, inspect them before writing claims.
- Create or update a standalone HTML file. Start from
assets/technical-doc-template.html when useful, then replace sample content with the user's real content.
- Keep content concise and structured: title, context, sections, tables, endpoint/config examples, warnings, and implementation notes.
- Render to PDF with
scripts/render_html_to_pdf.js or an equivalent browser print workflow.
- Verify the output before delivery: inspect page count, extract PDF text for removed/required phrases, and review a screenshot or rendered pages for layout issues.
- Deliver both HTML and PDF paths when both are generated.
Visual Rules
Read references/natural-technical-style.md when creating or redesigning a document. Core rules:
- Use a white A4 page on a subtle gray workspace.
- Use 1px borders, dotted separators, and flat tonal layers instead of heavy shadows or gradients.
- Use small status dots and monospace labels for technical metadata.
- Keep radius small, usually 4px.
- Avoid oversized hero sections, decorative blobs, loud palettes, heavy badges, and artificial SaaS styling.
- Keep tables and code blocks compact, but leave enough whitespace for scanning.
- Do not depend on remote CDNs or web fonts unless the user explicitly wants that.
Content Rules
- Verify technical facts from source files, configs, APIs, or user-provided material whenever possible.
- Separate operational setup, credentials, environment variables, endpoints, payloads, validation, and deployment notes into clear sections.
- Mark secrets and credentials as placeholders; never include real secrets.
- State environment variables only when they are actually needed or relevant.
- For branch-specific or version-specific claims, use exact names and dates only when verified.
- Preserve user-requested removals. After edits, search generated text for phrases the user asked to remove.
Template
Use assets/technical-doc-template.html as a starting point for A4 HTML reports. It includes:
- Three print-ready pages.
- Header, section kicker, footer, provider/config cards, tables, callouts, and code blocks.
- CSS variables for a muted technical palette.
- Print rules for stable PDF generation.
Copy it into the target workspace, rename it for the document, and edit the content directly. Keep the CSS local unless the target project already has a documented design system.
Rendering
Use the bundled renderer when Playwright is available:
node /path/to/technical-documentation/scripts/render_html_to_pdf.js input.html output.pdf preview.png
When using Codex's bundled runtime, set NODE_PATH to the bundled Node modules directory if plain node cannot resolve Playwright.
If Playwright is not available in the active Node environment, use the workspace dependency runtime when present, install dependencies only with user approval if needed, or fall back to the browser/PDF tools available in the environment.
After rendering, verify:
- PDF page count matches the intended document.
- Important headings and required notes are present.
- Removed phrases are absent.
- No blank trailing pages were generated.
- Text does not overlap or clip in the screenshot/PDF.
1---2name: technical-documentation3description: Create polished technical documentation as clean HTML and PDF artifacts with a natural developer-documentation aesthetic. Use when Codex is asked to generate, redesign, or export technical reports, implementation guides, onboarding documents, API/configuration summaries, architecture notes, endpoint catalogs, setup checklists, or similar docs that should look professional without feeling artificial, overly corporate, or too plain.4---56# Technical Documentation78## Overview910Build technical documentation as a source HTML file plus an exported PDF. Favor a calm, documentation-native visual language: readable type, restrained color, thin borders, dotted separators, status dots, clear tables, and code blocks that feel like a developer artifact rather than a marketing deck.1112## Workflow13141. Clarify the document purpose, audience, source facts, and final format. If source code or configs exist locally, inspect them before writing claims.152. Create or update a standalone HTML file. Start from `assets/technical-doc-template.html` when useful, then replace sample content with the user's real content.163. Keep content concise and structured: title, context, sections, tables, endpoint/config examples, warnings, and implementation notes.174. Render to PDF with `scripts/render_html_to_pdf.js` or an equivalent browser print workflow.185. Verify the output before delivery: inspect page count, extract PDF text for removed/required phrases, and review a screenshot or rendered pages for layout issues.196. Deliver both HTML and PDF paths when both are generated.2021## Visual Rules2223Read `references/natural-technical-style.md` when creating or redesigning a document. Core rules:2425- Use a white A4 page on a subtle gray workspace.26- Use 1px borders, dotted separators, and flat tonal layers instead of heavy shadows or gradients.27- Use small status dots and monospace labels for technical metadata.28- Keep radius small, usually 4px.29- Avoid oversized hero sections, decorative blobs, loud palettes, heavy badges, and artificial SaaS styling.30- Keep tables and code blocks compact, but leave enough whitespace for scanning.31- Do not depend on remote CDNs or web fonts unless the user explicitly wants that.3233## Content Rules3435- Verify technical facts from source files, configs, APIs, or user-provided material whenever possible.36- Separate operational setup, credentials, environment variables, endpoints, payloads, validation, and deployment notes into clear sections.37- Mark secrets and credentials as placeholders; never include real secrets.38- State environment variables only when they are actually needed or relevant.39- For branch-specific or version-specific claims, use exact names and dates only when verified.40- Preserve user-requested removals. After edits, search generated text for phrases the user asked to remove.4142## Template4344Use `assets/technical-doc-template.html` as a starting point for A4 HTML reports. It includes:4546- Three print-ready pages.47- Header, section kicker, footer, provider/config cards, tables, callouts, and code blocks.48- CSS variables for a muted technical palette.49- Print rules for stable PDF generation.5051Copy it into the target workspace, rename it for the document, and edit the content directly. Keep the CSS local unless the target project already has a documented design system.5253## Rendering5455Use the bundled renderer when Playwright is available:5657```bash58node /path/to/technical-documentation/scripts/render_html_to_pdf.js input.html output.pdf preview.png59```6061When using Codex's bundled runtime, set `NODE_PATH` to the bundled Node modules directory if plain `node` cannot resolve Playwright.6263If Playwright is not available in the active Node environment, use the workspace dependency runtime when present, install dependencies only with user approval if needed, or fall back to the browser/PDF tools available in the environment.6465After rendering, verify:6667- PDF page count matches the intended document.68- Important headings and required notes are present.69- Removed phrases are absent.70- No blank trailing pages were generated.71- Text does not overlap or clip in the screenshot/PDF.
lechuit