Use this skill whenever the user wants to write, edit, review, or structure pgEdge documentation. This includes: creating new documentation files, editing existing docs, setting up MkDocs project structure from the pgEdge template, writing README files, formatting markdown content, creating changelogs, structuring navigation, or reviewing docs for style compliance. Trigger whenever the user mentions writing docs, documentation, README, mkdocs, changelog, or asks to review/fix doc formatting. Also trigger when setting up a new project's documentation scaffolding. Do NOT trigger for code-only changes that happen to be in markdown (e.g., editing a CLAUDE.md or DESIGN.md with development guidelines).
This skill ensures all pgEdge documentation follows consistent style, formatting, and structural conventions. These rules apply across all pgEdge projects and repositories.
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.
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
When creating documentation scaffolding for a new project:
template/ contents into the project root.mkdocs.yml, replace <PROJECT NAME> with the actual project
name and <PROJECT REPO> with the GitHub repository name.docs/index.md, replace <PROJECT NAME> with the project name.docs/changelog.md, replace <PROJECT NAME> with the project
name.nav: section in mkdocs.yml to match the project's
documentation structure..md files in the docs/ directory.The template mkdocs.yml uses MkDocs Material with:
admonition, pymdownx.details, and pymdownx.superfences
markdown extensions.The nav: section defines the left-hand table of contents. Keep it
synchronized with the actual files in docs/.
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).
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:
The exception is "the Control Plane" which always takes the article.
my_file.md (lowercase,
underscores).docs/ folder or its subdirectories.README.md,
CONTRIBUTING.md).LICENSE.md file must be stored inside the docs/ folder;
aliases from other folders do not work properly with MkDocs.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
[text](URL) must remain unbroken on a single line, even if
it exceeds 79 characters. Break prose before or after the link.#).##) for sections.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.
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.
Capitalize SQL keywords; use lowercase for variables.
Include links to third-party software documentation where referenced.
Include links to the pgEdge GitHub repo when referring to cloning or working on the project.
Do not create links to github.io.
[text](URL) syntax must stay on one line.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.
## Next Steps) at the end of
tutorial and conceptual guide documents.Every public repository should have a README.md with the following
structure.
#) with the project name.## Table of Contents heading.docs/.The following section titles are exceptions to the gerund rule:
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):
Include a short introduction describing the project, what it does, and why someone might use it.
The following sections should appear in order:
## Installation - An introductory sentence, then:
## Configuration - An introductory sentence, then:
## Using <Project Name> - An introductory sentence, then:
## Documentation - An introductory sentence, then:
## Support & Resources:
## Contributing (if applicable):
Include a link to docs.pgedge.com: "For more information, visit docs.pgedge.com."
## License (at the end):
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.
Use the Keep a Changelog format with
Semantic Versioning. The
template file at template/docs/changelog.md provides the starting
structure.
The nav: section in mkdocs.yml defines the left-hand navigation
pane. It should mirror the README TOC and may include: