docs: explain PGDATA new values

[thomasboussekey]

and fix markdown warnings in README

[phillipross]

These code blocks seem to be rendering incorrectly. Maybe because they are indented?

[phillipross]

Typo fix opportunity: I believe "Recomendations" should be spelled "Recommendations"

[phillipross]

Thanks for fixing this and cleaning up. I've added two comments as requests for changes.

[ImreSamu]

Thank you very much for the PR!

I have two small pieces of feedback:

1.) For Postgres >=18 it is probably better to recommend using /var/lib/postgresql instead of /var/lib/postgresql/18/docker.
see: docker-library/postgres#1364 (comment)

I tested with:

• docker run -d -v $(pwd)/gisdata:/var/lib/postgresql -e POSTGRES_PASSWORD=test postgis/postgis:18-3.6

and inside the container the data is automatically placed in the new path:
fixing permissions on existing directory /var/lib/postgresql/18/docker ... ok
pg_ctl -D /var/lib/postgresql/18/docker -l logfile start

On the host I can also see the files created under ./gisdata/18/docker/:

# ls ./gisdata/18/docker/
base          pg_dynshmem    pg_logical    pg_replslot   pg_stat      pg_tblspc    pg_wal                postgresql.conf
global        pg_hba.conf    pg_multixact  pg_serial     pg_stat_tmp  pg_twophase  pg_xact               postmaster.opts
pg_commit_ts  pg_ident.conf  pg_notify     pg_snapshots  pg_subtrans  PG_VERSION   postgresql.auto.conf  postmaster.pid

So it looks like we should really follow the upstream suggestion, since that path is version-independent.
But please also double-check this on your side.

---

I usually refresh the README.md table with the one generated by ./update.sh.
That means the current table formatting will be overwritten during the next update.
I just wanted to mention this in advance, so please don’t take it personally if the formatting gets replaced later.

---

From the above, my first remark is probably the more important one.

[ImreSamu]

If you don’t mind, I’d like to add a few small changes.
From here - I’ll take over the PR - and finish it in the next couple of day ( since it’s not very urgent. )

[ImreSamu]

WIP

Still working on this ; a few small formatting details are not perfect yet.
Just wanted to let you know it’s not forgotten ;

here’s the current status:

• Added some warnings about the pg18 VOLUME path change (hopefully this will prevent a few upgrade-related issues).
• Improved the update.sh + apply-readme.md workflow so that README.md is updated automatically whenever ./update.sh is run.
• Added a short section about pg18 + io_uring.
• Removed most extra spaces to avoid hitting the 25000-char docker hub README limit (sorry about that).
• I also reformatted a few parts to match my personal style - apologies if that feels subjective.

I still see a few minor issues, but I’ll polish them soon and hand it over for review.

[ImreSamu]

READY to review:
Changes ( my 2 commits )

• Automated README maintenance: update.sh now stamps the autogenerated tables and runs the new apply-readme.sh helper to insert the _dockerlists_*.md tables, refresh the versions date, and warn if the README exceeds Docker Hub’s size limit.

• Reworked the opening of README.md to highlight the PostgreSQL 18 volume-path breaking change and improve the io_uring section.

• Noted that Docker Hub Markdown is limited, so contributors should stick to plain, platform-compatible Markdown (for example, avoid > [!CAUTION] callouts).

• Ran ./update.sh, which refreshed the 16-master and 17-master Dockerfiles.

• Additional copy-editing and formatting polish across README.md.

[ImreSamu]

Hi @thomasboussekey,

I made some significant changes, and here is the proposed new README.md:

• https://github.com/postgis/docker-postgis/blob/d0c36b1c0a96f141346f2209452f74359637aae7/README.md

Please take a look when you have time.

I think it’s a bit better now, but there’s still room for improvement.

One key takeaway is that Docker Hub’s Markdown (https://hub.docker.com/r/postgis/postgis)
is not fully compatible with GitHub’s Markdown,
so we should avoid using special syntax like > [!CAUTION].

[thomasboussekey]

Looks fine!
Great work @ImreSamu