Can I define a custom source or folder from which my site hosted on GitHub pages can load from?

Instead of the normal options as the source for my site deployed with pages, that is the master branch or the docs folder in the master branch, can I define another source, like a folder called site or pages or some custom name.

This will be really helpful, as I really like using specific names for my repo folders.


From, the only three options that GitHub Pages recognizes are:

  • master branch
  • docs/ folder on the master branch
  • gh-pages branch

So it doesn’t look like you’re able to define a custom folder or branch yet.


Yea @50wliu, true. Thank you for helping out, I am grateful.

I agree with @osioke, being able to choose a custom folder name would be great — I was about to create a post on this topic, but since I’ve found this thread I just joined in, so I’ll share here some thoughts on this.

I find that having only the “docs/” folder as an option for serving GH-Pages contents directly within the main repository is very limiting. The idea of hosting the GH-Pages contents inside the repo is a really cool feature, which I use a lot for online documentation, since it allows smart reuse of the repository contents to generate the documentation without having to work across orphan branches.

But in most cases, I find the “docs” folder name problematic, for I’d rather use that folder for the software/project documentation, whereas for the GH-Pages contents a folder named “www” would have been more intuitive and practical  — or at least the freedom to rename the folder as I please.


@50wliu I do not have gh-pages branch. Only the ‘master’ and ‘docs/folder’ branch. Is there anything I can do about this?

There is also a special case for user pages (Those directly available under which is, that they only accept the master branch as an option. Every other option is not selectable.

(Bit late on a response but better late then never I guess?)

With GitHub Actions could you setup an action, that would listen for pushes towards a specific folder (your www folder for example), take the content from it, build it, if nessesary and then pushes it towards the gh-pages branch.
That way could you have your custom folder while still using what GitHub offers.

1 Like

@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).