@andre601, I like your suggestion of using GitHub Actions to publish on the
gh-pages branch — it also allows to spare having to host the HTML files in the source repo (in case of docs being built from a lightweight markup syntax).
But I still think that in some case it might be desirable to have the HTML files inside the project, e.g. when the documentation is intended for both online and offline reading.
Being able to customize the GHPages folder name would be quite practical, and would allow to accommodate the user’s naming convention — e.g.
www for the built HTML docs, and
www-src for the markdown/AsciiDoc source, etc.
Mainly, I think that naming the default GHPages folder
docs was not an ideal choice, for many projects would rather use that folder name to host documentation, whereas the website might be just an introductory page presenting the project.
If the folder was named
gh-pages in the first place, this wouldn’t be an issue, but since many GitHub repositories are also hosted on other platforms (GitLab, Bitbucket, etc.) it would probably be too restrictive — hence the proposal of using
www instead, which is a common folder name used on LAMP/WAMP stacks (at least as an alias).