{"id":21158300,"url":"https://github.com/simbo/gh-pages-example","last_synced_at":"2025-08-08T02:17:46.452Z","repository":{"id":141795853,"uuid":"134148011","full_name":"simbo/gh-pages-example","owner":"simbo","description":"Example project for creating and maintaining github pages","archived":false,"fork":false,"pushed_at":"2018-05-24T18:21:25.000Z","size":345,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-14T15:30:17.066Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://simbo.github.io/gh-pages-example/","language":"CSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simbo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-20T12:20:08.000Z","updated_at":"2018-05-24T18:17:39.000Z","dependencies_parsed_at":null,"dependency_job_id":"9f872b24-42f6-4880-bee0-22a96b47180e","html_url":"https://github.com/simbo/gh-pages-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/simbo/gh-pages-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgh-pages-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgh-pages-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgh-pages-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgh-pages-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simbo","download_url":"https://codeload.github.com/simbo/gh-pages-example/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simbo%2Fgh-pages-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269351910,"owners_count":24402678,"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","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-20T12:19:41.400Z","updated_at":"2025-08-08T02:17:46.414Z","avatar_url":"https://github.com/simbo.png","language":"CSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"gh-pages-example\n================\n\n  \u003e An example project and tutorial for creating and deploying *GitHub Pages*\n  \u003e projects using custom build tools and *Travis CI*.\n\n---\n\n### *Demo Website at [simbo.github.io/gh-pages-example](https://simbo.github.io/gh-pages-example)*\n\n[![Travis CI build status](https://travis-ci.org/simbo/gh-pages-example.svg?branch=master)](https://travis-ci.org/simbo/gh-pages-example/builds)\n\n---\n\n- [About this project](#about-this-project)\n  - [Types of GitHub Pages](#types-of-github-pages)\n- [Assumed preconditions](#assumed-preconditions)\n- [Deployment strategy](#deployment-strategy)\n  - [Deploying using Travis CI](#deploying-using-travis-ci)\n  - [Deploying manually](#deploying-manually)\n- [Good to know](#good-to-know)\n- [Feedback](#feedback)\n\n---\n\n\n## TL;DR\n\n  - push your pages project sources to `master` branch while generated files are\n    added to `.gitignore`\n\n  - enable Travis CI using\n    [pages deployment](https://docs.travis-ci.com/user/deployment/pages/) to\n    build from `master` branch and push only generated files to `gh-pages`\n    branch (see final [`.travis.yml`](#deployment-config))\n\n  - [GitHub personal access token](https://github.com/settings/tokens) with\n    access scope `public_repo` is required for pushing from Travis CI\n\n\n## About this project\n\nThis example project demonstrates a clean and convenient strategy to create and\ndeploy *GitHub Pages* projects.\n\nIt focuses on setups, where pages are generated by a custom build tool (like\nwebpack, gulp or whatever) and not automatically generated by GitHub using\nJekyll or markdown. Although those type of projects could also benefit from\nshown workflows.\n\nIf you are not familiar with *GitHub Pages*' core concepts, you may want to head\nover to the [official documentation](https://pages.github.com/) first.\n\n\n### Types of GitHub Pages\n\nThere are two types of GitHub Pages: *project pages* and *user or organization\npages*.\n\nBoth offer the same features, while there are some important differences:\n\n\n  - *Project Pages* (i.e. `your-username.github.io/your-project`)  \n    …for creating pages for your project.  \n    can be published from:\n      - `gh-pages` branch\n      - `master` branch\n      - `master` branch `docs/` folder\n\n\n  - *User/Organization Pages* (i.e. `your-username.github.io`)  \n    …for creating your personal user pages or organization pages.  \n    can *only* be published from `master` branch\n\n\n#### *NOTICE:*\n\n  \u003e This document focuses on *project pages* that are published from a `gh-pages`\n  \u003e branch, as this is *imho* the most usual and convenient usecase.\n\n\u003c/div\u003e\n\nI suppose that, after reading this tutorial, you will be able to change\nconfiguration settings according to your needs to publish your *user pages* or\nwhatever you want to do.\n\n\n## Assumed preconditions\n\nYou have just created your new website project and your project root looks\nsomehow like this:\n\n``` text\n./\n├─ dist/          # generated pages\n├─ src/           # sources and templates\n├─ .gitignore     # `dist/` folder is ignored\n├─ package.json   # project metadata and tasks\n└─ README.md      # project information\n```\n\nThe `dist/` folder should be added to `.gitignore` as we do not want to commit\ngenerated files to our source branches.\n\nEverything else should be committed to your git repository's `master` branch and\npushed to GitHub.\n\n\n## Deployment strategy\n\nThe concept is simple:\n\n  \u003e While your generated `dist/` folder is ignored for the `master` branch, you\n  \u003e have another branch `gh-pages` that only contains the generated contents of\n  \u003e `dist/`, which will be automatically published at your GitHub pages URL.\n\nThis is easy to achieve using a CI/CD service like *Travis CI* but can also be\ndone manually.\n\n\n### Deploying using Travis CI\n\n\n#### Preparations\n\n\n##### Enable Travis CI support\n\nIf not done already, register at [Travis CI](https://travis-ci.org/) using your\nGitHub account and install the\n[travis client](https://github.com/travis-ci/travis.rb) on your machine.\n\nEnable Travis support for your project by running `travis init` in your project\nroot. When asked for main language, choose what fits your needs (i.e. `node`).\n\nAfterwards, there should be a fresh generated `.travis.yml` in your project\nroot.\n\n\n##### GitHub personal access token\n\nGo to GitHub and get a\n[personal access token](https://github.com/settings/tokens), so Travis will be\nauthorized to push changes back to GitHub. Give it a useful description like\n`my-project travis deploy` and select `public_repo` as access scope.\n\nAfter generating the token, encrypt it and add it to your Travis config:\n\n``` bash\ntravis encrypt GITHUB_TOKEN=your-personal-access-token --add\n```\n\n\n##### Deployment config\n\nTravis offers the\n[GitHub Pages deployment provider](https://docs.travis-ci.com/user/deployment/pages/),\nwhich fullfills all our needs automagically.\n\nWith deployment options, your final `.travis.yml` should look like this:\n\n``` yaml\nlanguage: node_js\nnode_js:\n- '8.11.*'\n\nenv:\n  global:\n    secure: PDS4pIbrZhQaB…  # encrypted github token\n\nscript:\n- npm run build             # build script\n\ndeploy:\n  provider: pages\n  github-token: $GITHUB_TOKEN\n  on:\n    branch: master          # trigger deploys only from master branch\n  local-dir: dist           # path to generated pages\n  target-branch: gh-pages   # target branch for deploy\n  skip-cleanup: true        # keep generated files from build script\n  keep-history: true        # keep git history in gh-pages branch\n```\n\nIf not already existing, the `gh-pages` branch will be automatically created on\nthe first deploy.\n\nAfterwards, you can enable *GitHub Pages* support in your repository settings\non GitHub. Make sure to set the build source to `gh-pages` branch.\n\n*You're done!*\n\n\n#### Triggering deploys\n\nEvery pushed commit to `master` should now automatically trigger a build and\npush updates to `gh-pages`, which will be published at the respective URL.\n\n\n### Deploying manually\n\n  \u003e I do not recommend to use manual deployment as a common strategy. Although it\n  \u003e seems simple, it's prone to human error. Nevertheless, it's good to know…\n\nWe're assuming the same preconditions as for deploying with Travis:\n`dist/` folder is ignored while everything else is pushed to `master` with no\ncurrent changes in the working tree.\n\n\n#### Preparations for manual deploy workflow\n\n\n##### Create `gh-pages` branch\n\nYou can skip branch creation if you already have a branch `gh-pages` on your\nGitHub remote.\n\n``` bash\n# create a new orphan branch `gh-pages` and clear its working tree\ngit checkout --orphan gh-pages\ngit rm -rf .\n\n# create an `index.html` and commit it\necho \"Hello World\" \u003e index.html\ngit add index.html\ngit commit -m \"initial content\"\n\n# push `gh-pages` branch to github\ngit push origin gh-pages\n\n# switch back to `master` branch and delete `gh-pages` locally\ngit checkout master\ngit branch -d gh-pages\n```\n\nAfterwards, you can enable *GitHub Pages* support in your repository settings\non GitHub. Make sure to set the build source to `gh-pages` branch.\n\n\n##### Clone `gh-pages` to `dist/`\n\nNow clone the `gh-pages` branch to the `dist/` folder inside of your repo.\nThis way your build script will generate files directly into `gh-pages`.\n\n``` bash\n# remove generated dist folder if existing\nrm -rf dist\n# clone only `gh-pages` to `dist/`\ngit clone git@github.com:USER/PROJECT.git --branch gh-pages --single-branch dist\n```\n\n\n#### Manual deployment steps\n\n``` bash\n# run build script\nnpm run build\n# go to `dist/` to commit and push generated changes\ncd dist\ngit add -r .\ngit commit -m \"update content\"\ngit push origin gh-pages\n```\n\nWhen using manual deployment like this, make sure that your build script\ndoesn't touch the repository inside of `dist/`. You may want to build a little\nscript for the deployment steps (or better\n[use Travis CI for deployment](#deploying-using-travis-ci) directly).\n\n\n## Good to know\n\n  - `index.html` vs. `README.md`\n\n    There will be a conflict if you have both of these in your `gh-pages`\n    root, as GitHub seems indecisive which one of them to use per default…\n\n\n## Feedback\n\nFeel free to use\n[project issues](https://github.com/simbo/gh-pages-example/issues) for\ndiscussion and comments.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimbo%2Fgh-pages-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimbo%2Fgh-pages-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimbo%2Fgh-pages-example/lists"}