{"id":51312394,"url":"https://github.com/pgedge/3rd-party-docs","last_synced_at":"2026-07-01T05:02:06.724Z","repository":{"id":343687103,"uuid":"1178751859","full_name":"pgEdge/3rd-party-docs","owner":"pgEdge","description":"3rd party PostgreSQL and community documentation in MKDocs format","archived":false,"fork":false,"pushed_at":"2026-05-14T12:31:13.000Z","size":49099,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T14:29:07.615Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pgEdge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-11T10:31:01.000Z","updated_at":"2026-05-14T12:28:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pgEdge/3rd-party-docs","commit_stats":null,"previous_names":["pgedge/postgresql-docs","pgedge/3rd-party-docs"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pgEdge/3rd-party-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgEdge%2F3rd-party-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgEdge%2F3rd-party-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgEdge%2F3rd-party-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgEdge%2F3rd-party-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pgEdge","download_url":"https://codeload.github.com/pgEdge/3rd-party-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pgEdge%2F3rd-party-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34993438,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-01T05:02:04.104Z","updated_at":"2026-07-01T05:02:06.716Z","avatar_url":"https://github.com/pgEdge.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostgreSQL \u0026 Component Documentation\n\n[![CI](https://github.com/pgEdge/postgresql-docs/actions/workflows/ci.yml/badge.svg)](https://github.com/pgEdge/postgresql-docs/actions/workflows/ci.yml)\n\nMkDocs Material documentation sites converted from upstream\nsources:\n\n- **PostgreSQL** — SGML/DocBook sources converted to Markdown\n- **pgAdmin 4** — reStructuredText (RST) sources converted to\n  Markdown\n- **PostgREST** — reStructuredText (RST) sources converted to\n  Markdown\n- **PostGIS** — XML/DocBook sources converted to Markdown\n- **psycopg2** — reStructuredText (RST) sources converted to\n  Markdown\n- **pgBackRest** — Custom XML sources converted to Markdown\n- **PgBouncer** — Markdown sources (split/copied)\n- **pgvector** — Markdown sources (split by section)\n- **pgAudit** — Markdown sources (split by section)\n- **pg_vectorize** — MkDocs site (imported with upstream nav)\n- **pg_tokenizer** — Markdown sources (multi-file copy)\n- **vchord_bm25** — Markdown sources (split by section)\n- **pg_cron** — Markdown sources (split by section)\n- **pgmq** — MkDocs site (imported with upstream nav)\n- **pg_stat_monitor** — Markdown sources (split by section)\n- **pldebugger** — Markdown sources (split by section)\n- **system_stats** — Markdown sources (split by section)\n\n## How It Works\n\nThis project uses an unconventional git branching model. The\n`main` branch contains **only** the Go converter tooling, a\nskeleton `mkdocs.yml`, and MkDocs support files (CSS, images,\noverrides). It contains no documentation content.\n\nAll generated documentation lives on **product/version\nbranches**. Each branch is an orphan-like branch that combines\nthe tooling from `main` with the converted Markdown output for\none product at one version. The `build-all.sh` script automates\nthis: for each branch it checks out the branch, merges tooling\nfrom `main`, clones/fetches the upstream source, runs the\nconverter, and commits the result.\n\nThis means:\n\n- **Tooling changes** go on `main` and propagate to all\n  branches on the next build.\n- **Generated docs** are never committed to `main` — each\n  branch is self-contained with its own `docs/` and\n  `mkdocs.yml`.\n- Each branch can be independently deployed as a standalone\n  MkDocs Material site.\n\n## Branch Layout\n\n| Branch | Product | Source Format |\n|--------|---------|---------------|\n| `pg16` .. `pg19` | PostgreSQL 16–19 | SGML (`doc/src/sgml/`) |\n| `pgadmin911` .. `pgadmin913` | pgAdmin 4 v9.11–v9.13 | RST (`docs/en_US/`) |\n| `pgadminmaster` | pgAdmin 4 dev | RST (`docs/en_US/`) |\n| `postgrest145` | PostgREST v14.5 | RST (`docs/`) |\n| `postgrestmaster` | PostgREST dev | RST (`docs/`) |\n| `postgis355`, `postgis362` | PostGIS 3.5–3.6 | XML/DocBook (`doc/`) |\n| `postgismaster` | PostGIS dev | XML/DocBook (`doc/`) |\n| `psycopg2910` | psycopg2 v2.9.10 | RST (`doc/src/`) |\n| `psycopg2master` | psycopg2 dev | RST (`doc/src/`) |\n| `pgbackrest257` .. `pgbackrest258` | pgBackRest 2.57–2.58 | Custom XML (`doc/`) |\n| `pgbackrestmaster` | pgBackRest dev | Custom XML (`doc/`) |\n| `pgbouncer124` .. `pgbouncer125` | PgBouncer 1.24–1.25 | Markdown (`doc/`) |\n| `pgbouncermaster` | PgBouncer dev | Markdown (`doc/`) |\n| `pgvector080` .. `pgvector081` | pgvector 0.8.0–0.8.1 | Markdown (`README.md`) |\n| `pgvectormaster` | pgvector dev | Markdown (`README.md`) |\n| `pgaudit161` .. `pgaudit180` | pgAudit 16.1–18.0 | Markdown (`README.md`) |\n| `pgauditmaster` | pgAudit dev | Markdown (`README.md`) |\n| `pgvectorize0260` | pg_vectorize v0.26.0 | MkDocs (`docs/`) |\n| `pgvectorizemaster` | pg_vectorize dev | MkDocs (`docs/`) |\n| `pgtokenizer011` | pg_tokenizer v0.1.1 | Markdown (`docs/`) |\n| `pgtokenizermaster` | pg_tokenizer dev | Markdown (`docs/`) |\n| `vchordbm25030` | vchord_bm25 v0.3.0 | Markdown (`README.md`) |\n| `vchordbm25master` | vchord_bm25 dev | Markdown (`README.md`) |\n| `pgcron167` | pg_cron v1.6.7 | Markdown (`README.md`) |\n| `pgcronmaster` | pg_cron dev | Markdown (`README.md`) |\n| `pgmq1110` | pgmq v1.11.0 | MkDocs (`docs/`) |\n| `pgmqmaster` | pgmq dev | MkDocs (`docs/`) |\n| `pgstatmonitor231` | pg_stat_monitor v2.3.1 | Markdown (`README.md`) |\n| `pgstatmonitormaster` | pg_stat_monitor dev | Markdown (`README.md`) |\n| `pldebugger19` | pldebugger v1.9 | Markdown (`README-pldebugger.md`) |\n| `pldebuggermaster` | pldebugger dev | Markdown (`README-pldebugger.md`) |\n| `systemstats321` | system_stats v3.2.1 | Markdown (`README.md`) |\n| `systemstatsmaster` | system_stats dev | Markdown (`README.md`) |\n\n## Prerequisites\n\n- Go 1.25+\n- [yq](https://github.com/mikefarah/yq) (for `build-all.sh`)\n- Python 3 with\n  [MkDocs Material](https://squidfunk.github.io/mkdocs-material/)\n\n## Quick Start\n\n### Build All Branches\n\nThe `build-all.sh` script automates the full pipeline:\ncloning/fetching upstream repos, converting docs, and\ncommitting to each branch. All branches are defined in\n`branches.yml`.\n\n```sh\n# Build everything\n./build-all.sh\n\n# Build only PostgreSQL branches\n./build-all.sh --branches \"pg*\"\n\n# Build specific branches\n./build-all.sh --branches pg17,postgrest145\n\n# Preview what would be built\n./build-all.sh --dry-run\n```\n\nAfter building, the script shows a summary and prompts to\npush updated branches to the remote.\n\n### Build a Single Branch Manually\n\nFor manual builds, checkout the target branch, provide the\nupstream source, and run the converter:\n\n```sh\n# PostgreSQL (SGML mode)\nmake convert SRC_DIR=/path/to/postgresql/doc/src/sgml \\\n    VERSION=17.2\n\n# pgAdmin 4 (RST mode)\nmake convert-rst SRC_DIR=/path/to/pgadmin4/docs/en_US \\\n    VERSION=9.13\n\n# PostgREST (RST mode, suppressing Sponsors section)\nmake convert-rst SRC_DIR=/path/to/postgrest/docs \\\n    VERSION=v14.5 SKIP_SECTIONS=\"Sponsors\"\n\n# pgBackRest (backrest mode, via binary directly)\n./bin/pgdoc-converter -mode backrest \\\n    -src /path/to/pgbackrest/doc -version dev -verbose\n\n# pgvector (Markdown mode)\nmake convert-md SRC_DIR=/path/to/pgvector \\\n    VERSION=\"pgvector v0.8.0\"\n\n# PgBouncer (Markdown mode)\nmake convert-md SRC_DIR=/path/to/pgbouncer/doc \\\n    VERSION=\"PgBouncer 1.25\"\n```\n\nPreview the site locally:\n\n```sh\nmkdocs serve\n```\n\n## Builder\n\nThe `builder/` directory contains a Go tool\n(`pgdoc-converter`) that converts upstream documentation to\nMarkdown suitable for MkDocs Material. It supports five\nconversion modes:\n\n### SGML Mode (PostgreSQL)\n\n- Entity resolution and SGML parsing\n- DocBook-to-Markdown conversion (100+ element handlers)\n- `func_table_entry` tables split into multi-column layout\n- Two-pass conversion: ID map then content generation\n- Image copying from the PostgreSQL source tree\n\n### XML Mode (PostGIS)\n\n- Standard XML/DocBook parsing via Go's `encoding/xml`\n- Entity and XInclude resolution\n- WKT geometry diagrams rendered to inline SVG\n- Image path rewriting for `use_directory_urls`\n\n### RST Mode (pgAdmin, PostgREST, psycopg2)\n\n- Line-by-line RST parser (headings, directives, lists,\n  grid tables, labels, substitutions, literal blocks)\n- Toctree resolution for hierarchical nav structure\n- Directive handlers: image, code-block, admonitions,\n  csv-table, list-table, grid tables (including merged\n  cells), container, tabs, youtube, literalinclude, topic,\n  Sphinx domain directives, and more\n- Inline markup: `:ref:`, `:doc:`, external links, bold,\n  italic, literal, substitutions, index entries\n- Cross-reference resolution via label scanning\n- HTML rendering for complex table cells (bullet lists,\n  inline formatting)\n- Dark/light mode image support via MkDocs Material\n  `#only-dark`/`#only-light` fragments\n- Section suppression (`-skip-sections` flag)\n- Project name inference from Sphinx `conf.py`\n\n### Backrest Mode (pgBackRest)\n\n- Custom XML parser for pgBackRest's proprietary DTD\n  (not DocBook)\n- Entity resolution for `\u003c!ENTITY name SYSTEM \"path\"\u003e`\n  declarations (used heavily in release notes)\n- `{[key]}` variable substitution with multi-pass\n  resolution for chained references\n- Block definitions (`\u003cblock-define\u003e`/`\u003cblock\u003e`) for\n  reusable content fragments\n- Executable documentation: `\u003cexecute-list\u003e` commands\n  rendered as bash code blocks with optional output\n- Configuration blocks: `\u003cbackrest-config\u003e` and\n  `\u003cpostgres-config\u003e` rendered as INI code blocks\n- Self-closing brand elements (`\u003cbackrest/\u003e`, `\u003cpostgres/\u003e`,\n  `\u003cexe/\u003e`)\n- Semantic inline elements (`\u003cfile\u003e`, `\u003cpath\u003e`, `\u003ccmd\u003e`,\n  `\u003cbr-option\u003e`, etc.) rendered as inline code\n- Cross-page link resolution with section path splitting\n  (e.g. `quickstart/perform-restore`)\n- Multi-page documents split by top-level `\u003csection\u003e`;\n  single-page for small docs (FAQ, metrics, etc.)\n- Nav titles derived from subtitle when title is just the\n  project name\n\n### Markdown Mode (PgBouncer, pgvector, pgAudit)\n\n- Single-file projects split by H2 headings into separate\n  pages with promoted heading levels\n- Multi-file projects copied with auto-generated index page\n- Internal anchor links rewritten across split files\n- GitHub Alerts converted to MkDocs admonitions\n- Non-doc files filtered (fragments, changelogs, etc.)\n\n### MkDocs Mode (pg_vectorize)\n\n- Imports upstream projects that already have an `mkdocs.yml`\n- Uses upstream nav structure verbatim (no inference)\n- Merges upstream `markdown_extensions` and `plugins` into\n  the skeleton config (deduplicating, skipping unsupported\n  plugins like `mkdocstrings`)\n- Resolves `pymdownx.snippets` includes inline at copy time\n- Copies entire docs tree preserving directory structure\n\n### Shared\n\n- MkDocs nav YAML generation from document structure\n- Automatic `md_in_html` extension injection\n- Link validation (broken links, missing anchors)\n- Common types (`FileEntry`, `IDEntry`, `MarkdownWriter`)\n\n### Makefile Targets\n\n| Target | Description |\n|--------|-------------|\n| `build` | Compile the converter to `bin/` |\n| `test` | Run all Go tests |\n| `lint` | Run `gofmt` and `go vet` |\n| `convert` | Build and run the SGML converter |\n| `convert-rst` | Build and run the RST converter |\n| `convert-md` | Build and run the Markdown converter |\n| `validate` | Build and run with link validation |\n| `clean` | Remove the compiled binary |\n| `setup` | Configure git hooks |\n\n### Command-Line Options\n\n```\npgdoc-converter [flags]\n  -mode           Conversion mode: sgml, xml, rst, md,\n                  or backrest (default \"sgml\")\n  -src            Path to source documentation directory\n  -out            Output directory for .md files\n                  (default \"./docs\")\n  -mkdocs         Path to mkdocs.yml (default \"./mkdocs.yml\")\n  -version        Version label (e.g. \"17.2\" or \"9.13\")\n  -copyright      Copyright string (RST mode only)\n  -pgadmin-src    Path to pgAdmin source tree (for\n                  literalinclude directives, RST mode only)\n  -skip-sections  Comma-separated section headings to suppress\n                  (RST mode only, e.g. \"Sponsors,Changelog\")\n  -validate       Run link validation after conversion\n  -verbose        Show detailed progress\n```\n\n### Makefile Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SRC_DIR` | `/doc-source` | Path to upstream documentation |\n| `OUT_DIR` | `./docs` | Output directory |\n| `MKDOCS` | `./mkdocs.yml` | MkDocs configuration file |\n| `VERSION` | (empty) | Version label for site_name |\n| `COPYRIGHT` | (empty) | Copyright string (RST mode) |\n| `PGADMIN_SRC` | (empty) | pgAdmin source (RST mode) |\n| `SKIP_SECTIONS` | (empty) | Sections to suppress (RST mode) |\n\n## TODO: Additional Component Docs Sites\n\n- [x] PostgreSQL (SGML converter)\n- [x] pgAdmin 4 (RST converter)\n- [x] PgBouncer (1.24–1.25)\n- [x] pgBackRest (2.57–2.58)\n- [x] PostGIS (3.5.5–3.6.2)\n- [x] pgvector (0.8.0–0.8.1)\n- [x] pgAudit (16.1–18.0)\n- [x] psycopg2 (2.9.10)\n- [x] PostgREST (14.5)\n- [x] pg_vectorize (v0.26.0)\n- [x] pg_tokenizer (v0.1.1)\n- [x] vchord_bm25 (v0.3.0)\n- [x] pg_cron (v1.6.7)\n- [x] pgmq (v1.11.0)\n- [x] pg_stat_monitor (v2.3.1)\n- [x] pldebugger (v1.9)\n- [x] system_stats (v3.2.1)\n\n## Project Structure\n\n```\nbuild-all.sh        Build orchestration script\nbranches.yml        Branch/product configuration\nbuilder/            Go converter source\n  backrest/           pgBackRest custom XML converter\n  convert/            SGML-to-Markdown conversion\n  md/                 Markdown splitter and copier\n  nav/                MkDocs nav YAML generation\n  rst/                RST parser, converter, directive handlers\n  sgml/               SGML tokenizer, parser, entity resolver\n  shared/             Shared types and Markdown writer\n  validate/           Link validation\n  wkt/                WKT geometry to SVG renderer (PostGIS)\ndocs/               MkDocs support files (on main branch)\n  img/                Site images (logo, favicon)\n  overrides/          MkDocs Material template overrides\n  stylesheets/        Custom CSS\nmkdocs.yml          MkDocs skeleton configuration\nMakefile            Build targets\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgedge%2F3rd-party-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpgedge%2F3rd-party-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpgedge%2F3rd-party-docs/lists"}