pgedge-docs

pgEdge Documentation Writing Skill

This skill ensures all pgEdge documentation follows consistent style, formatting, and structural conventions. These rules apply across all pgEdge projects and repositories.

Project Setup from Template

When setting up documentation for a new pgEdge project, copy the template files from the template/ directory alongside this SKILL.md file into the target project. Use cp -r to copy the entire template directory tree in one operation so that all subdirectories are created automatically.

Template Contents

The template provides a minimal MkDocs Material configuration with pgEdge branding:

template/
  mkdocs.yml                          # MkDocs Material config
  LICENSE.md                          # Root copy of PostgreSQL License
  docs/
    index.md                          # Landing page
    changelog.md                      # Keep a Changelog format
    LICENSE.md                        # PostgreSQL License (for MkDocs)
    img/
      favicon.ico                     # pgEdge favicon
      logo-dark.png                   # Dark mode logo
      logo-light.png                  # Light mode logo
    overrides/
      partials/
        logo.html                     # Light/dark logo switcher
    stylesheets/
      extra.css                       # Light/dark mode CSS

Setting Up a New Project

When creating documentation scaffolding for a new project:

1. Copy the entire template/ contents into the project root.
2. In mkdocs.yml, replace <PROJECT NAME> with the actual project name and <PROJECT REPO> with the GitHub repository name. Strip a leading "pgEdge " (case-insensitive) from the project name before substituting — the theme already renders the pgEdge logo, and site_name: pgEdge X would double it up next to the logo. The GitHub repo name (<PROJECT REPO>) is whatever the user actually uses for the repository slug; do not normalize that.
3. In docs/index.md, replace <PROJECT NAME> with the project name.
4. In docs/changelog.md, replace <PROJECT NAME> with the project name.
5. Build out the nav: section in mkdocs.yml to match the project's documentation structure.
6. Create the corresponding .md files in the docs/ directory.

mkdocs.yml Configuration

The template mkdocs.yml uses MkDocs Material with:

• admonition, pymdownx.details, and pymdownx.superfences markdown extensions.
• Light/dark mode palette switching with pgEdge branding.
• Custom logo partial for light/dark mode logos.
• Navigation features: instant loading, tracking, pruning, scroll to top, and TOC following.

The nav: section defines the left-hand table of contents. Keep it synchronized with the actual files in docs/.

Integration with the Primary Documentation Site

The primary pgEdge documentation site (the pgedge-docs repository, published at docs.pgedge.com) uses the MkDocs multirepo plugin to import documentation from individual project repositories. Each project is imported via a !import directive in the primary site's mkdocs.yml referencing the project's GitHub repo and branch:

- v1.0: '!import https://github.com/pgEdge/project.git?branch=v1.0'

This means each project's mkdocs.yml and docs/ folder must be self-contained and valid on their own. Do not add configuration that only works in the primary site context (e.g., multirepo plugin, redirects plugin, analytics, consent banners, nav_categories, or versioned_docsets).

Product Names

The following product names are proper nouns; treat them as such. As a rule, omit "the" in front of the name unless using it as an adjective to describe software, files, or other artifacts:

• pgEdge Cloud
• pgEdge Enterprise Postgres
• pgEdge Distributed Postgres
• Enterprise Postgres
• Distributed Postgres
• pgEdge Postgres
• pgEdge AI Toolkit
• Spock
• LOLOR (aka lolor)
• ACE
• pgEdge Vectorizer
• Snowflake
• pgEdge Postgres MCP Server
• pgEdge Anonymizer
• pgEdge RAG Server
• pgEdge Docloader

The exception is "the Control Plane" which always takes the article.

File Naming and Organization

File Names

• Documentation files use the form my_file.md (lowercase, underscores).
• All docs live in the docs/ folder or its subdirectories.
• Root-level markdown files use UPPERCASE names (README.md, CONTRIBUTING.md).
• The LICENSE.md file must be stored inside the docs/ folder; aliases from other folders do not work properly with MkDocs.

Directory Layout

Each project should have:

docs/
  index.md            # Main landing page
  changelog.md        # Release notes in Keep a Changelog format
  LICENSE.md          # PostgreSQL License
  img/                # Images and branding assets
  overrides/          # MkDocs Material overrides
  stylesheets/        # Custom CSS

Line Length and Wrapping

• Wrap lines at 79 characters.
• Wrap prose as close to 79 characters as possible without exceeding 79 characters; the only exceptions are hyperlinks and table content, which must not be split (see the following bullets).
• Never split hyperlinks across lines. The complete markdown link syntax [text](URL) must remain unbroken on a single line, even if it exceeds 79 characters. Break prose before or after the link.
• Never split table columns across lines.
• Replace em-dashes with regular dashes (hyphens).

Writing Style

Voice and Tone

• Write in active voice.
• Use full, grammatically correct sentences between 7 and 20 words.
• Use a semicolon to link similar ideas within a sentence.
• Use articles (a, an, the) when appropriate.
• Do not refer to an object as "it" unless the referent is in the same sentence. The pronoun is too ambiguous.

What to Avoid

• Do not use bold font as headings; MkDocs sometimes misinterprets bold text as a heading and adds it to the navigation pane. Bold within inline text is fine and will not be misinterpreted.
• Do not use hashtags in front of steps in numbered lists; every step containing a # is added to the navigation pane on the upper-right side of the documentation page.
• Do not use fragments in bulleted or stepped lists; for example, avoid items of the form "Semantic matching: uses pgvector for similarity-based cache lookups".
• Remove bold highlighted text content that is not inline; some software misinterprets it as a heading level.

Heading Structure

• Each file has one first-level heading (#).
• Use multiple second-level headings (##) for sections.
• Use third and fourth-level headings for sub-sections beneath the hierarchically previous heading level.
• Every heading must be followed by an introductory sentence or paragraph explaining what the section covers.
• Never use bold font within a heading.

Bulleted Lists

• Bulleted lists should complete sentences ending with periods.
• Use a lead-in sentence before the list that ends with a colon.
• The lead-in and bullet items together should form grammatically complete sentences.
• Keep lead-in sentences concise; use "include:" or "is useful for:" rather than verbose phrases like "include the following operations:" or "is useful for the following purposes:".
• When bullet items are gerunds (verb forms ending in -ing), they should work grammatically with the lead-in sentence.
• Items that complete the opening sentence start with a lowercase letter (unless a proper noun or code element) and end with a period.
• Items that are fragments or do not complete the introductory sentence start with uppercase and do not end in punctuation.
• Bullet items end only with periods, never semicolons; semicolons are reserved for linking related ideas within sentences.
• Always leave a blank line before the first item in any list.

Correct example:

The view includes:

- the total entries and expired entries.
- the total cache size in megabytes.
- the average access count per entry.

Incorrect example:

The view includes the following metrics:

- The view shows the total entries and expired entries.
- The view shows the total cache size in megabytes.
- The view shows the average access count.

Numbered Lists

• Reserve numbered lists for sequential procedures (installation steps, setup instructions, troubleshooting workflows) where order is critical.
• A numbered list should always consist of steps that must be performed in the order listed; if the steps can be performed in a random order and still work, they belong in a bulleted list.
• Convert non-sequential content (feature lists, examples, comparisons) to bulleted lists or narrative format.
• Use an introductory sentence before each numbered list.
• Leave a blank line before the first item.
• Each entry should introduce the step with a complete and correct sentence.
• Indent code blocks properly within numbered list items, formatted using the rules above.
• Do not use bold font in numbered lists.

Code Formatting

• Use an explanatory sentence before every code block that ends with a colon, identifying the command and describing what it does.

• Use single backticks for a single command or line of code: `SELECT * FROM my_table;`

• Use fenced code blocks with a language tag for multi-line code:

  ```sql
  SELECT * FROM code;
  ```
  

• stdio, stdin, stdout, and stderr should always be in backticks (courier font).

• Capitalize command keywords; use lowercase for variables.

• Include links to third-party software installation and documentation pages where referenced.

• Include links to the pgEdge GitHub repo when referring to cloning the repo or working on the project.

• Do not create links to github.io.

Tables

• Every table must have an introductory sentence immediately before it, using the pattern: "The following table [describes/shows/compares] X:".
• The introductory sentence should be in active voice and explain what the table contains.
• No icons or emojis in tables. Remove all emoji and icon characters (for example, lightning bolts, checkmarks, floppy disks) from table cells and replace with descriptive text such as Fast, Good, or High.
• Keep table content professional and accessible.
• Use plain text only; no bold font in cells.
• Avoid special characters that may not render correctly in all formats.
• Use words rather than symbols to convey meaning.

Hyperlinks

• The complete [text](URL) syntax must stay on one line.
• Break prose before or after the link, never within it.
• This rule supersedes the 79-character line length limit.

Features and Overview Sections

If a page has a "Features" or "Overview" section after the introductory paragraph, do not start with a heading. Instead, use a sentence like: "The MCP Server includes the following features:", followed by a bulleted list.

Troubleshooting Sections

• Add troubleshooting content to a dedicated Troubleshooting section, not at the end of multiple individual doc files.
• Sort the Troubleshooting section and use sub-sections for topics like connection issues, authentication issues, and API-related issues.

Next Steps Sections

• Include a "Next Steps" section (## Next Steps) at the end of tutorial and conceptual guide documents.
• Provide 2-4 bulleted links to related documentation.
• Each bullet should be a complete sentence describing what the linked document covers, using the pattern: "- The Document Name document describes/explains/provides X.".
• Do not include "Next Steps" in reference docs, API docs, FAQs, or troubleshooting guides.
• For FAQ and troubleshooting documents, use a support/contact section instead (e.g., "Still Have Questions?").

README File Structure

Every public repository should have a README.md with the following structure.

Header

• A first-level heading (#) with the project name.
• Links to regression testing or developer tools if applicable.
• GitHub Action badges for important actions.

Table of Contents

• A ## Table of Contents heading.
• A bulleted list linking to files in docs/.
• Use gerunds in section titles where possible.

The following section titles are exceptions to the gerund rule:

• Architecture
• Overview
• Getting Started
• Release Notes
• FAQ
• Developer Resources
• Reference sections

Suggested TOC Structure

Top-level entries should mirror the mkdocs.yml nav and link to the same .md files; second-level links may reference anchors within a file (docs/file_name.md#section_name):

• Architecture Guide
• Best Practices Guide
• Getting Started/Quick Start
• Building the Project (including prerequisites)
• Installing the Project
• Configuring the Project (with Advanced Configuration)
• Using the Project
• Upgrading the Project Installation
• Managing an Installation
• Modifying a Deployed Project
• Monitoring/Logging
• Performance
• Function Reference (with links to individual function pages)
• API Reference
• Troubleshooting
• FAQ
• Release Notes
• Developer Resources

After the TOC

Include a short introduction describing the project, what it does, and why someone might use it.

Standard Sections

The following sections should appear in order:

## Installation - An introductory sentence, then:

• Prerequisite software or configuration.
• Installing with pgEdge software (e.g., the Control Plane) if applicable.
• Building from source.

## Configuration - An introductory sentence, then:

• Simple configuration steps.
• A link to advanced configuration options.

## Using <Project Name> - An introductory sentence, then:

• Simple usage instructions and examples.
• Links to advanced usage pages.

## Documentation - An introductory sentence, then:

• Details about building documentation from source.
• Links to the pgEdge documentation site.

## Support & Resources:

• Links to help and documentation: "For more information, visit here."
• A link to the Issues page: "To report an issue with the software, visit:" followed by the link.

## Contributing (if applicable):

• "We welcome your project contributions; for more information, see docs/developers.md."

Include a link to docs.pgedge.com: "For more information, visit docs.pgedge.com."

## License (at the end):

• "This project is licensed under the PostgreSQL License."

Copyright Notice

Copyright years appear in three template files: mkdocs.yml, LICENSE.md, and docs/LICENSE.md. All three use the <CURRENT YEAR> placeholder. When setting up a new project or editing an existing one, replace every <CURRENT YEAR> placeholder with the actual current year.

Changelog Format

Use the Keep a Changelog format with Semantic Versioning. The template file at template/docs/changelog.md provides the starting structure.

mkdocs.yml Navigation Structure

The nav: section in mkdocs.yml defines the left-hand navigation pane. It should mirror the README TOC and may include:

nav:
  - Architecture Guide
  - Best Practices Guide
  - Installing this Project:
      - Getting Started/Quick Start
      - Building the Project:
          - Prerequisites
      - Installation
      - Configuring this Project:
          - Advanced Configuration
      - Upgrading the Project
  - Using the Project:
      - Connecting to the Project
      - Project Usage Instructions
  - Using Project Management Features:
      - Modifying the Installation
      - Monitoring/Logging
      - Performance
  - Function Reference
  - API Reference
  - Troubleshooting
  - FAQ
  - Release Notes
  - Developer Resources

Nested details can be in the same file as the parent section (e.g., Prerequisites can live in the same file as Installation).

Verification Against Code

After writing or editing documentation, launch a sub-agent to verify that the documentation accurately and completely reflects what the code actually implements. This verification step is mandatory; do not skip it.

What to Verify

The sub-agent should read the relevant source code and confirm:

• every command line option, flag, and argument documented on the page exists in the code, and every option in the code appears in the documentation.
• every configuration option, environment variable, or setting documented on the page exists in the code, and every such option in the code appears in the documentation.
• default values, valid ranges, and accepted value types match what the code defines.
• descriptions of behavior (what a flag does, what a config controls) match the actual implementation.
• documented function signatures, parameters, and return values match the source code.
• any version requirements, prerequisites, or compatibility notes are consistent with the codebase.

How to Run Verification

After completing documentation changes, launch a sub-agent with a prompt that identifies the documentation file(s) and the corresponding source file(s), and asks the sub-agent to:

1. Read the documentation that was written or modified.
2. Read the corresponding source code that implements the documented functionality.
3. Compare the two and report any discrepancies - missing items, incorrect defaults, mismatched descriptions, or outdated information.
4. List any options, flags, parameters, or settings found in the code that are not documented.
5. List any documented items that do not exist in the code.

Fix all discrepancies before considering the documentation complete.

Review Checklist

When reviewing documentation, verify:

• One # heading per file
• Every heading followed by an introductory sentence
• Lines wrapped at 79 characters (hyperlinks excepted)
• No bold used as headings
• No em-dashes (use hyphens)
• No fragments in lists
• Bulleted lists have lead-in sentences ending with colons
• Numbered lists used only for sequential procedures
• Code blocks have language tags and explanatory sentences
• Tables have introductory sentences and no emojis
• Product names treated as proper nouns
• No ambiguous "it" references
• Hyperlinks not split across lines
• Blank lines before all lists
• Active voice throughout
• All command line options/flags in the code are documented
• All configuration options in the code are documented
• Default values and valid ranges match the code
• Behavioral descriptions match the actual implementation
• Sub-agent verification against source code completed

In-App Help Panel Content (Online Help)

When This Section Applies

These rules apply when authoring help content rendered inside an application's help panel. The section activates when the user mentions "in-app help", "online help", "help panel", "help content", or "help pages", or when the working project contains client/src/components/HelpPanel/pages/ (an artifact of the pgedge-webapp skill).

File Locations and Layout

Each help page is one Markdown file under client/src/components/HelpPanel/pages/ paired with a thin React wrapper that imports the Markdown and feeds it to a shared renderer. The Markdown filename is kebab-case matching the page's route key. Register every page in pages/index.ts with { key, title, component }. When adding a page, add the markdown, the wrapper, and the registry entry in a single change.

Page Structure

In-app help follows the same writing rules as user-facing docs (one # heading, intro paragraph after every heading, lead-in colons before lists, product names as proper nouns, line wrap at 79), with three differences appropriate to the in-app context:

• No "Next Steps" section. The Help panel is a side drawer; users return to the application, not to another doc page.
• No external links to docs.pgedge.com from in-app pages — instead, link to other help pages via [label](page:<key>). The renderer rewrites these links to navigate within the panel.
• Pages should stay short. Anything over ~400 words is a candidate to split or to relocate to docs.pgedge.com.

React-Markdown Rendering Constraints

The Help panel uses react-markdown plus remark-gfm. This means:

• Standard CommonMark plus GFM tables, task lists, and strikethrough are supported.
• Admonitions are not supported. Wrap content in MUI <Alert severity="info"> inside the wrapper, not in Markdown.
• Custom HTML in Markdown is sanitized; inline <style> and <script> will not render.
• Code fences with language tags work via react-syntax-highlighter.

Linking Between Pages

Use [label](page:<key>) for in-panel links. Do not use https://docs.pgedge.com/... from in-app help; if depth is needed, summarize and link with target="_blank" rel="noopener".

Images and Assets

Images live alongside the markdown in client/src/components/HelpPanel/pages/img/<page-key>/ and are bundled by Vite. Provide alt text on every image.

Verifying In-App Help Content

The verification rule from the user-facing-docs section also applies to in-app help. After authoring or editing any page, launch a sub-agent that confirms documented behavior matches the actual code.

OpenAPI Browser (Online API Reference)

When This Section Applies

When the working project ships a REST API and a docs/api/openapi.json file (auto-detected via .pgedge-webapp.json from the pgedge-webapp skill, or any project with docs/api/openapi.json plus a docs/api/browser.md page).

Convention

Mirror the pattern used by pgedge-postgres-mcp and ai-dba-workbench. The mkdocs.yml declares the redoc-tag plugin in its plugins: list (no version pin):

plugins:
  - search
  - redoc-tag

The browser page lives at docs/api/browser.md. It uses a hide: [toc, navigation] frontmatter and inline CSS to hide the mkdocs chrome around the embedded Redoc iframe; the body is a single <redoc src="openapi.json"/> tag plus a small script that re-applies inherited colors inside the iframe. The full page is shipped verbatim in the pgedge-webapp template at template/docs/api/browser.md — copy it as-is.

The OpenAPI specification lives at docs/api/openapi.json and is regenerated from the server binary by make openapi:

make openapi

This invokes <binary> --generate-openapi-spec (or -openapi, matching the project's flag name) and redirects stdout to the file. The file should be committed; CI re-runs make openapi and diffs against the committed copy to catch drift.

Adding the API Browser to a Scaffolded Project

When pgedge-docs scaffolds a docs site for a project that has docs/api/openapi.json:

1. Add redoc-tag to the plugins: list in mkdocs.yml.
2. Add a nav entry for the API browser:

   - For Developers:
       - API Browser: api/browser.md
   

3. Confirm docs/api/browser.md exists (it ships with pgedge-webapp templates).
4. Run mkdocs build --strict to verify the page renders without warnings.