{"id":13665257,"url":"https://github.com/sbt/sbt-ghpages","last_synced_at":"2026-01-10T19:42:10.197Z","repository":{"id":3306340,"uuid":"4348430","full_name":"sbt/sbt-ghpages","owner":"sbt","description":"git, site and ghpages support for sbt projects.","archived":false,"fork":true,"pushed_at":"2024-10-29T00:26:44.000Z","size":134,"stargazers_count":91,"open_issues_count":25,"forks_count":20,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-10-29T01:25:08.866Z","etag":null,"topics":["github-pages","sbt","sbt-plugin"],"latest_commit_sha":null,"homepage":"","language":"Scala","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"marmbrus/xsbt-ghpages-plugin","license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sbt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2012-05-16T15:21:19.000Z","updated_at":"2024-10-29T00:26:48.000Z","dependencies_parsed_at":"2023-01-16T21:15:56.338Z","dependency_job_id":"9c325cdb-1595-4735-9510-1302d530a471","html_url":"https://github.com/sbt/sbt-ghpages","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-ghpages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-ghpages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-ghpages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sbt%2Fsbt-ghpages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sbt","download_url":"https://codeload.github.com/sbt/sbt-ghpages/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224031926,"owners_count":17244361,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["github-pages","sbt","sbt-plugin"],"created_at":"2024-08-02T06:00:30.980Z","updated_at":"2026-01-10T19:42:10.146Z","avatar_url":"https://github.com/sbt.png","language":"Scala","funding_links":[],"categories":["DOCUMENTATION","Table of Contents","Sbt plugins"],"sub_categories":["Sbt plugins"],"readme":"# sbt-ghpages #\n\nThe GitHub Pages plugin for sbt makes it simple to publish a project website to\n[GitHub Pages](https://pages.github.com/).\n\nFirst, you need a site to publish, or you may wish to start simply with your\nproject's Scaladoc API documentation. The [sbt-site plugin] has you covered: it\ncan help to manage several popular static site generation tools automatically\nfrom sbt.\n\nStart by setting up `sbt-site`, and once you have it locally generating a site\nand/or Scaladoc to your liking, `sbt-ghpages` will integrate to publish it on\nthe web with GitHub Pages where it will be served at\n`https://{your username}.github.io/{your project}/`.\n\n[sbt-site plugin]: https://github.com/sbt/sbt-site\n\n\n## Adding the plugin to your project ##\n\n*Note, sbt-ghpages now requires the use of sbt version 0.13.5 or greater.*\n\nCreate a `project/ghpages.sbt` file that looks like the following:\n\n```scala\naddSbtPlugin(\"com.github.sbt\" % \"sbt-ghpages\" % \"0.8.0\")\n```\n\nThen in your `build.sbt` file, simply enable the GhpagesPlugin via an\n`enablePlugins` statement for your project, and specify the location of\nyour github repository (for more information on enabling and disabling sbt plugins,\nsee the [sbt plugin documentation](https://www.scala-sbt.org/1.x/docs/Using-Plugins.html#Enabling+and+disabling+auto+plugins)):\n\n```scala\nenablePlugins(GhpagesPlugin)\n\ngit.remoteRepo := \"git@github.com:{your username}/{your project}.git\"\n```\n### Settings\n\nsbt-ghpages provides the following optional setting keys for use in your `build.sbt` file:\n\n- `ghpagesRepository` - Location of the sandbox repository to be used to check out the gh-pages branch.\n- `ghpagesNoJekyll` - If set to true will cause a .nojekyll file to be generated, to prevent GitHub from running Jekyll on pushed sites.\n- `ghpagesBranch` - Name of the branch in which to store static files. Defaults to gh-pages.\n\n\n## Initializing the gh-pages branch ##\n\nGitHub Pages works by processing the contents of a special branch in your\nproject repository named `gh-pages` and then serving your static files.\n\nBefore using `sbt-ghpages`, you must [create the `gh-pages` branch in your\nrepository][create branch] and push the branch to GitHub. The quick steps are:\n\n    # Using a fresh, temporary clone is safest for this procedure\n    $ pushd /tmp\n    $ git clone git@github.com:youruser/yourproject.git\n    $ cd yourproject\n\n    # Create branch with no history or content\n    $ git checkout --orphan gh-pages\n    $ git rm -rf .\n\n    # Establish the branch existence\n    $ git commit --allow-empty -m \"Initialize gh-pages branch\"\n    $ git push origin gh-pages\n\n    # Return to original working copy clone, we're finished with the /tmp one\n    $ popd\n    $ rm -rf /tmp/yourproject\n\nNow that this is done, you can begin using the plugin with sbt.\n\n[create branch]: https://help.github.com/articles/creating-project-pages-using-the-command-line/\n\n\n## Publishing your site ##\n\nSimply run the `ghpagesPushSite` task to publish your website.\n\n### How it works\n\nBehind the scenes, `sbt-ghpages` will create a new \"sandbox\" clone of your Git\nrepository, with its location determined by the `ghpagesRepository` setting key\n(by default set to a directory under `~/.sbt/ghpages`). Whenever you run `sbt ghpagesPushSite`\nit will copy your site content into that sandbox repository, commit it to the\n`gh-pages` branch, and push the branch to GitHub.\n\nThe sandbox repo approach spares you from doing the `gh-pages` checkout/commit\ndance yourself each time you update your site content, while avoiding any\nmistakes with dirty or untracked files in your normal working copy clone.\n\n\n## Publishing Scaladoc\n\nA common use for `sbt-ghpages` is to automate the publishing of Scaladoc. If you wish to\nuse it for this, first ask `sbt-site` to generate your Scaladoc by adding an `enablePlugins` directive\nfor the `SiteScaladocPlugin` (included in sbt-site) to your `build.sbt` see the\n[sbt-site documentation](https://www.scala-sbt.org/sbt-site/api-documentation.html) for more information:\n\n```scala\nenablePlugins(SiteScaladocPlugin)\n```\n\nAfter using `ghpagesPushSite` you should find your Scaladoc at:\n\n`https://{your username}.github.io/{your project}/latest/api`\n\nIf you aren't publishing any other content to the root of your project site, it\nis recommended that you add a redirect to provide a better experience for users\nvisiting it. You can do this by creating a page in `src/site/index.html` that\nautomatically redirects to either the above link, or even better, to a good\nstarting point in your documentation. Otherwise, people visiting `https://{your\nusername}.github.io/{your project}` will just get a 404.\n\nHere's an example `src/site/index.html` you can use as a starting point:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml lang=\"en\"\u003e\n\u003chead\u003e\n    \u003cmeta charset=\"UTF-8\"\u003e\n    \u003ctitle\u003eProject Documentation\u003c/title\u003e\n    \u003cscript language=\"JavaScript\"\u003e\n    \u003c!--\n    function doRedirect()\n    {\n        window.location.replace(\"latest/api\");\n    }\n\n    doRedirect();\n    //--\u003e\n    \u003c/script\u003e\n\u003c/head\u003e\n\u003cbody\u003e\n\u003ca href=\"latest/api\"\u003eGo to the project documentation\n\u003c/a\u003e\n\u003c/body\u003e\n\u003c/html\u003e\n```\n\n## Protecting Existing Files\nThe default behaviour of sbt-ghpages is to remove all existing files in the Github Pages repository\nprior to publishing current pages. sbt-ghpages supports customisation of this behaviour via the provided\n`includeFilter in ghpagesCleanSite` and/or `excludeFilter in ghpagesCleanSite` setting keys.\n\nsbt-ghpages will only delete files which are matched by the FileFilter specified by the\n`includeFilter in ghpagesCleanSite` setting key AND are not matched by the FileFilter specified by the\n`excludeFilter in ghpagesCleanSite` key.\n\nFor example, to prevent sbt-ghpages from deleting the \"CNAME\" file located at the root of your site, and any file\nnamed \"versions.html\", add the following to your build.sbt:\n\n```scala\nexcludeFilter in ghpagesCleanSite :=\n  new FileFilter{\n    def accept(f: File) = (ghpagesRepository.value / \"CNAME\").getCanonicalPath == f.getCanonicalPath\n  } || \"versions.html\"\n```\n\nFor more information on creating more complex filters, please refer to the [sbt FileFilter documentation](https://www.scala-sbt.org/1.x/docs/Paths.html#File+Filters).\n\n\n## LICENSE ##\n\nCopyright (c) 2008, 2009, 2010, 2011 Josh Suereth, Steven Blundy, Josh Cough, Mark Harrah, Stuart Roebuck, Tony Sloane, Vesa Vilhonen, Jason Zaugg\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions\nare met:\n1. Redistributions of source code must retain the above copyright\n   notice, this list of conditions and the following disclaimer.\n2. Redistributions in binary form must reproduce the above copyright\n   notice, this list of conditions and the following disclaimer in the\n   documentation and/or other materials provided with the distribution.\n3. The name of the author may not be used to endorse or promote products\n   derived from this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR\nIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES\nOF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.\nIN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,\nINCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT\nNOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,\nDATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\nTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT\n(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF\nTHIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n\nNote:\nThis plugin is adapted from the sbt 0.10.x source code for general usage among projects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-ghpages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsbt%2Fsbt-ghpages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsbt%2Fsbt-ghpages/lists"}