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

[osioke]

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.

[winstliu]

From https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/, 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.

[a0a7]

@Paul-Browne How? Is there anywhere I can read more?

[rayluo]

FWIW, this is the solution Github Page Overwriter I came up with and have been using.

[Andre601]

I legit don't get the point of that action tho... What is the problem with hosting your website's files on the repo (if I understand it right)?
You can keep it in a separate branch and have it build when pushing to it, before deploying.

I can't see where it "polutes" the git history here. If anything does that even help keeping things transparent.

[airtower-luna]

You can also build and deploy a page without pushing the build result now, see: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

[rayluo]

I legit don't get the point of that action tho... What is the problem with hosting your website's files on the repo (if I understand it right)? You can keep it in a separate branch and have it build when pushing to it, before deploying.

I can't see where it "polutes" the git history here. If anything does that even help keeping things transparent.

@Andre601 , we already had similar conversation before. Please refer to this message and the 2 more after it. Your mindset seems remain unchanged "there is already an X, why invent a new Y". You just replaced your X1 in 2021 with a different X2 today. Well, probably the inventor of Y saw something lacking in X. And it is also possible that you need no more feature than X, in that case you do not feel a need to switch, which is totally fine.

The choice criteria is simple. If your repo's file structure already matches what you want to show as a website (for example, you already have an index.html in your root folder), you do not need any extra github actions. Just deploy it as-is to a github page, and you are all set. This github discussion started in 2017 for a reason, that the index.html file either is inside a sub folder, or does not even exist until an artifact is built. Now, in all fairness, that feature might have been satisfied by recent improvements in 2023 (although I still can't find it in luna's doc link above). As a user you can always shop around and pick the solution that suit you. I'm merely providing an option here.

P.S.: If you want to continue our discussion, please reply to that earlier message where we left off. I do not want to hijack this chosen answer link and "pollute" it.

[osioke]

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

[tajmone]

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.

[itsalaidbacklife]

I would love the flexibility to specify any directory of the project, and I agree that an alternative top-level predefined name which was more clear about intent would be preferable to docs. I suggest gh-pages as the folder name to match the predefined branch pattern, and to be even more explicit than www

[webdott]

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

[Andre601]

50wliu:

From https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ , 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.

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

[Andre601]

(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.

[tajmone]

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

[Thaina]

I want to have this as feature request. We should allowed to specified any folder of the repo as pages

From my used case, I have create my web repo with blazor. And the default folder it use for page is wwwroot. Which, if github pages allowed custom folder specified, I could specify github pages with wwwroot folder and just create my repo as that

[mluevanos]

Based on https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/ I am not sure if gh-pages branch is still an option.

I found: Deploy to `gh-pages` from a `dist` folder on the master branch. Useful for use with [yeoman](http://yeoman.io). · GitHub which is " Deploying a subfolder to GitHub Pages"

• I did not use this, I ended up moving my files to the root, but the discussion is still active
• Next time I publish a site I will probably just try to create a different branch with my index.html in there and select the branch from drop down as the publishing source. GitHub documentation/processes changes so much it’s difficult to know what will work!

[Andre601]

The gh-pages branch is still a thing.
In fact will GitHub automatically enable GitHub Pages, if a gh-pages branch was created, so it’s still supported.
I myself use this branch for various projects where I have the docs or similar on github.io

[rayluo]

@tajmone , @Andre601 , @mluevanos , et al, I encountered the same need, and - it took me much longer than expected but - I finally came up with a reusable Github Actions named Github Pages Overwriter to allow choosing arbitrary folder in your repo to publish it into Github Pages.

Give it a shot, spread the words if you like it, subscribe my project if you want to receive future updates, report issues here because I may not come back and check this post.

[Andre601]

There is already peaceiris/actions-gh-pages which does this job.
There, you can define your own folders from which the action would take the files to publish to the gh-pages branch.

[rayluo]

Hi @Andre601 , good point. And, yes, peaceires/actions-gh-pages was (and still is) among the top search results when I was evaluating existing solutions. Here come the major reasons that I eventually started the Github Pages Overwriter project.

1. The What It Does. I prefer a git tenet of never store build artifacts inside a repo (at least not store as part of the permanent history). Some existing github actions may possibly satisfy that, but none of them explicitly promises such behavior in their contract (i.e. their doc). I tested peaceires/actions-gh-pages just now. It always adds a new commit into the gh-pages branch. Not the way I prefer.

   In my new project, not only I name it “Github Page OVERWRITER” which hints that the generated content would be ephemeral and overwritten in next deployment, I also specifically documented that in “how does it work” section.

   In order to examine whether an existing Github Pages deployment action satisfies the aforementioned tenet, I’d need to look into their implementation. But, many of them turn out to be implemented by one programming language or another, running in some sort of container/runner. I certainly do not know all existing languages, so I cannot easily review any given 3rd-party github action. This brings me to my next point.

2. The How It Is Implemented. To satisfy tenet in Welcome to GitHub product feedback #1, one only needs to run several git commands in the right way, without much external dependency. Feel free to look into the “Github Page Overwritter” source code to see how it only uses git command line tool to achieve that. Personally, it took me less time to write a new action to do what I want, then to sieve through existing actions to see whether one of them happens to suit my need.

3. The Security. Any 3rd-party github action could potentially mess up with your central repo. Security concern on github action is a real thing. The only way to be sure, is to review their implementation. This is another reason why “Feature Request: Select a column when adding an issue to a project #2 how it is implemented” is important. I feel more comfortable to trust an action that I can fully understand what it works. So should you.

4. The Simplicity. Based on Welcome to GitHub product feedback #1 and Feature Request: Select a column when adding an issue to a project #2, there is really no much to configure. A simpler configuration means easier to get started.

   FWIW, Github Page Ovewriter does not require any github token to be configured. My attempts with the “Actions-gh-pages”, on the other hand, failed with "Error: Action failed with “not found deploy key or tokens” despite that the “github_token” is documented as optional in its doc.

Perhaps I should also include this essay into my project’s README file. :slight_smile:

[tajmone]

In the meantime, since this discussion took place, GitHub added a new option that allows using a custom-named branch (not just gh-branch).

[dangowans]

I would love the option of a www folder!

[auwsom]

Forgive my cynicism, but this seems silly. There is a dropdown for directories that could easily populate dirs other than /root or /docs.
I agree limiting to docs as a folder is bizarre for the current prevalence of static sites.
I would use a symlinked locally to a docs folder, but it doesnt work as git sees symlinks as files.
Actions seems like overkill for a common configuration of having a subdirectory for static site generation.
I tried this Gist, which creates a GithubPages branch: https://gist.github.com/cobyism/4730490 "Deploying a subfolder to GitHub Pages", but it looks like I would have to do this for every update.

KISS method: symlink the directory to another outside of the local repo and create a new repo for that directory. git init && git remote add origin [email protected]:<username>/<repo>.git

[Andre601]

Why not use the new option of GitHub Actions to push to pages?
GitHub implemented this option pretty much for this: To allow a lot more freedom in your setup.

[wsshin]

I would use a symlinked locally to a docs folder, but it doesnt work as git sees symlinks as files.

symlink works for me. Suppose your static site generator generates the output files in a specific folder, say website/. I think you probably did ln -s website docs. This doesn't work, because git sees the symbolic link docs as a file as you pointed out.

You should reverse the direction of the symlink: ln - s docs website. Then, when the static site generator generates files in website/, actually docs/ is populated. Now you can push the populated docs/ to GitHub to deploy the website.

This may not be an ideal solution, but it is a method that works for me.

[auwsom]

Ah, yes, the reverse would work. Thanks! Also, symlink the output dir a level up and create a new repo for it. This is what I've chosen as the separation of the generator with the site repos makes sense to me. I can gitignore the site output, and dev on the generator, while having CICD on the site repo when I edit/blog on it.

…

On Thu, Sep 15, 2022, 10:18 AM Wonseok Shin ***@***.***> wrote: I would use a symlinked locally to a docs folder, but it doesnt work as git sees symlinks as files. symlink works for me. Suppose your static site generator generates the output files in a specific folder, say website/. I think you probably did ln -s website docs. This doesn't work, because git sees the symbolic link docs as a file as you pointed out. You should reverse the direction of the symlink: ln - s docs website. Then, when the static site generator generates files in website/, actually docs/ is populated. Now you can push the populated docs/ to GitHub to deploy the website. This may not be an ideal solution, but it is a method that works for me. — Reply to this email directly, view it on GitHub <#23073 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AF7OL3HIGKOFZFVG3CEZKSLV6NK5XANCNFSM56VZTELQ> . You are receiving this because you commented.Message ID: ***@***.***>

[katbyte]

+1 for a custom path, limiting it to /docs and the root makes little sense

[Navil]

Is there any plan of implementing this in the near future? I feel like writing actions for such a basic configuration is an overkill.

[airtower-luna]

This has been implemented for a few months now, since you can use a custom deployment workflow: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

[Navil]

Yes, but only by writing a GitHub actions and taking care of the workflow myself, right?

[airtower-luna]

Yep, that's correct.

[askibinski]

In Github actions, see the path property for this.

[edison12a]

@askibinski Thanks!

[edison12a]

Final Solution:
Use github actions to deploy your pages. It lets you customize everything.

( Reported by @airtower-luna )

[SebastianTroy]

This would be super useful because I could place my files inside a directory with the same name as my repo, allowing me to migrate my website without changing every single in-site href to account for the new root directory name...

[kkarhan]

Anyone else think that this entire issue shouldn't exist and instead, GitHub Pages should just allow one to select any arbitrary folder instead?

Cuz it's really annoying and I just don't want to deal with GitHub Actions

at all!

Why even is there a menu then if they decide to only support 3 options at all...

[kkarhan]

The GitHub Pages Overwirter does work, but I still am mad about this frustration!

• Despite it being successfully working!

[airtower-luna]

You can us an actions workflow to publish your site, that way you can choose whatever path you want. A workflow that only publishes static files can be pretty simple: https://github.com/actions/starter-workflows/blob/main/pages/static.yml

[steveniles]

It kind of amazes me that this is still an issue...

What's being asked for here, is to be able to be able to make a simple, (for many people) one-time change to their repo settings, so the pages are hosted from another folder (that isn't precisely, exactly named "docs").

This is akin to asking for a hammer to deal with a nail that's sticking out.

And the recurring solution offered, to use Github Actions, is akin to responding "sorry, we don't have a hammer, just learn how to use a jackhammer".

As has been said, it's overkill for this use-case. Come on Github, you've already built quite a complex system here, right down to the drop-down box that already exists for selecting "root" or "docs". Just finish the 99% done job and let people pick another folder as their pages base.

"When all you have is a jackhammer..."

[shaunagm]

Adding myself to the list of people who would greatly prefer an option in the settings dropdown. I can and do use github actions regularly but I'm also a teacher and having to teach people github actions can double the length of a session in my 'building a static site with github' training

[rayluo]

... I can and do use github actions regularly but I'm also a teacher and having to teach people github actions can double the length of a session in my 'building a static site with github' training

Until github provides their built-in solution to customize source folder, you may take a look at Github Page Overwriter (GPO) which requires minimal configuration, so it hopefully won't double the length of your teaching session.

P.S. I am also in the list of people waiting here, and I am the author of that GPO.

[darkoverlordofdata]

years later, still the same dump problems this is why i've left github

[diskria]

Honestly, this limitation makes no sense.
I’m building Gradle plugins and using GitHub Pages as a static Maven repository — it works perfectly fine technically, except that I’m forced to put everything inside the docs folder.
GitHub already lets us pick any branch in the UI, so why is the folder name hard-coded?

There’s no real technical reason for this — it just adds friction for anyone who uses Pages for something slightly more advanced than a static HTML site.
At this point, it feels like a fixable design oversight that’s been ignored for years.

[rayluo]

I don't know Gradle/Maven but, out of curiosity, would Github Page Overwriter (GPO) help for your case? (Shameless plug: I am the author of that GPO tool.)

[darkoverlordofdata]

Another reason to switch to gitlab Bruce Davidson

…

On Fri, Dec 12, 2025, 5:53 AM Ryan Emberling ***@***.***> wrote: I would love the flexibility to specify any directory of the project, and I agree that an alternative top-level predefined name which was more clear about intent would be preferable to docs. I suggest gh-pages as the folder name to match the predefined branch pattern, and to be even more explicit than www — Reply to this email directly, view it on GitHub <#23073 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAJUE4QRMGVBHEI7D3NVYJL4BLCFRAVCNFSM6AAAAABZOZ3WJ6VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTKMRUGA3DAOI> . You are receiving this because you commented.Message ID: ***@***.***>