{"id":18613551,"url":"https://github.com/kim-hwiwon/Zola-Pages-Deployer","last_synced_at":"2025-04-10T23:32:04.836Z","repository":{"id":48009475,"uuid":"516225801","full_name":"kim-hwiwon/Zola-Pages-Deployer","owner":"kim-hwiwon","description":"Build and deploy Zola project to Repository Static Pages (GitLab/GitHub Pages) automatically, whenever pushed to remote repositories","archived":false,"fork":false,"pushed_at":"2022-08-05T07:49:25.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-18T03:42:59.001Z","etag":null,"topics":["github-pages","gitlab-pages","pages","zola"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kim-hwiwon.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":null,"security":null,"support":null}},"created_at":"2022-07-21T04:37:52.000Z","updated_at":"2022-08-01T08:05:41.000Z","dependencies_parsed_at":"2022-08-30T05:21:18.518Z","dependency_job_id":null,"html_url":"https://github.com/kim-hwiwon/Zola-Pages-Deployer","commit_stats":null,"previous_names":["hwiwon-kim/zola-pages-deployer","kim-hwiwon/zola-pages-deployer"],"tags_count":3,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FZola-Pages-Deployer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FZola-Pages-Deployer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FZola-Pages-Deployer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kim-hwiwon%2FZola-Pages-Deployer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kim-hwiwon","download_url":"https://codeload.github.com/kim-hwiwon/Zola-Pages-Deployer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248316431,"owners_count":21083443,"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","gitlab-pages","pages","zola"],"created_at":"2024-11-07T03:22:43.005Z","updated_at":"2025-04-10T23:32:04.467Z","avatar_url":"https://github.com/kim-hwiwon.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zola Pages Deployer\n\n  Build and deploy [Zola (static site generator)](https://www.getzola.org/) project to\n  [Repository Static Pages (*GitLab*/*GitHub* Pages)](#pages-deployment) automatically,  \n  whenever pushed to remote repositories (*GitLab*/*GitHub*)\n\n## Abstract\n\n  - Workflow on push to *GitLab*/*GitHub*\n    1. Build Zola project to a static site\n    2. [Optimize](#optimizer-pass) built output above\n       - Optimize Zola built result with optimizer passes\n       - Built-in optimizer\n         - `10_minify`: Minify text files (e.g. `.html`, `.js`, `.css`)\n         - `20_gzip_compression`: Perform static gzip compression on text files\n       - Add other optimizer scripts in addition to built-in ones\n    3. [Deploy](#pages-deployment) optimized output above to\n       [*GitLab* Pages](https://docs.gitlab.com/ee/user/project/pages/) / \n       [*GitHub* Pages](https://pages.github.com/)\n       - Supports [Pages Export on deploy](#pages-export)\n         (deploying built pages to an external repository),\n         not only to pushed repository\n  \n\n  - Use cases\n    - Build Zola \u0026 deploy Pages automatically on push\n      - Push to *GitLab*/*GitHub*, then *GitLab*/*GitHub* Pages site is deployed\n        (for *GitHub*, [configuration](#pages-deployment) is required)\n    - Build Zola in a repository A, but export \u0026 deploy the Pages outputs to another repository B\n      - It is possible to push \u0026 build source in a private repository A,\n        but deploy the outputs in public repository B\n\n\n\n## Quick Start\n\n  1. Git clone from this repository.\n     - From *GitLab*\n       ```shell\n       git clone -b v1.0.2 --single-branch https://gitlab.com/snoopy3476/zola-pages-deployer\n       cd zola-pages-deployer\n       git switch -c main\n       ```\n     - From *GitHub*\n       ```shell\n       git clone -b v1.0.2 --single-branch https://github.com/snoopy3476/zola-pages-deployer\n       cd zola-pages-deployer\n       git switch -c main\n       ```\n\n  2. Remove the sample zola project directory.\n     ('`~_sample_zola_project-remove_this_before_use`')\n     ```shell\n     git rm -rf ./~_sample_zola_project-remove_this_before_use\n     ```\n\n  3. Put a single Zola project directory in the Zola Pages Deployer directory.  \n     (NOTE: directory name '`optimizer`', '`public`', and '`static`' are reserved\n     and must not be used for inner Zola project directory!)\n\n  4. Build\n  \n     - Build on remote repositories automatically\n       - Push to *GitLab*/*GitHub*, then Zola project is built automatically on remote\n         - Built output is also deployed to Pages if pushed to ***default branch***\n     - Build locally\n       - Install prerequisites\n         - [`podman`](https://podman.io/) or [`docker`](https://www.docker.com/)\n       - Use following scripts:\n         - `./build.sh [zola-dir]`:\n           Build Zola project,\n           then put the result output inside the subdirectory '`public`'\n         - `./img-build.sh \u003cimg-name\u003e [zola-dir]`:\n           Build Zola project,\n           then put the result output inside the webserver OCI container image (`thttpd`)\n           so that it can be served via container\n         - `./test-img.sh [zola-dir]`:\n           Build Zola project inside webserver image (`thttpd`),\n           then run the Zola container created from the image.\n           Note that output image and container is removed after exit\n\n\n\n## Features\n\n  \u003e Following features are provided in addition to just building a Zola site.\n\n\n### Optimizer Pass\n  \n  \u003e After Zola build, optimizing the built result is done with optimizer passes\n    (which are in the directory '`optimizer`').\n  \n  - Optimizer pass files should have execute permission (e.g. `$ chmod +x opt_pass_file`)\n  - Optimizer passes inside the directory '`optimizer`' are run in ascending order of their filenames\n    - E.g. `00_first_script` \u003e `10_second_script` \u003e `20_third_script` \u003e ...\n  - Each optimizer runs at a temporary directory somewhere else,\n    which has two subdirectories: '`input`' and '`output`'\n    - All optimizers read files to optimize from '`input`' directory,\n      do optimize them,\n      then put the result files inside '`output`' directory\n    - Examples of optimizer files\n      - Just pass input as output, without any modification:\n        ```shell\n        #!/bin/sh\n        cp -af ./input/. ./output\n        ```\n      - Add gzip compressed results `(orig_filename).gz` for each input file:\n        ```shell\n        #!/bin/sh\n        cp -af ./input/. ./output \u0026\u0026 gzip -krf9 ./output\n        ```\n  - Place user-defined optimizers inside the directory '`optimizer`' to add custom passes in addition to built-in ones\n\n\n### Pages Deployment\n  \n  \u003e When this project is pushed to a remote repository,\n    Zola project is built into Pages automatically with *GitLab* CI / *GitHub* Actions.\n  \n  - Behaviors of the feature\n  \n    - On push to *GitLab*/*GitHub*, according to the pushed branch\n      - ***Default branch***:\n        1. First build Zola\n        2. Then deploy to *GitLab*/*GitHub* Pages\n      - Other branches:\n        1. Build Zola only\n    \n    - [When ***`Pages Export`*** is enabled](#pages-export)\n    \n  - Required configuration for *`GitHub Pages`*\n    - After first push and Pages branch creation,\n      [Configure *GitHub* Pages](https://docs.github.com/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site)\n      on the repository to server pages\n      - Set source branch to: *`pages`* (or your custom Pages branch in other name)\n      - Set directory to: '`/docs`'\n    - (Cf. No additional configuration is needed for *`GitLab Pages`*,\n      just push to *GitLab* and it is deployed)\n\n\n#### Pages Export\n\n  \u003e Export \u0026 deploy built result site outputs\n    to an *external repository*, not deploying to the pushed repository itself.\n    \n  - Behavior according to whether [environment variables for Pages Export](#environment-variables-for-pages-export) is configured\n    - Not configured:\n      1. Build \u0026 Deploy on pushed repository\n    - Configured:\n      1. First build on pushed repository\n      2. Then deploy on a ***different repository*** other than the pushed one\n\n\n\n## Environment Variables\n\n  \u003e Set following environment variables to control build and deploy process on *GitLab*/*GitHub*.\n  \n  - Environment variables can be set by:\n    - *GitLab*: Adding as variables in `Project Settings` \u003e `CI/CD` \u003e `Variables`\n    - *GitHub*: Adding as secrets in `Repository Settings` \u003e `Security` \u003e `Secrets` \u003e `Actions`\n    - Local run: Setting as environment variables (e.g. `$ ENV1=ENVVAR1 ENV2=ENVVAR2 ./build.sh`)\n  \n\n\n### Environment Variables for Build\n\n  \u003e These environment variables take effect on build stage on *GitLab*/*GitHub*, or local manual run.\n  \n  \n  - For Zola\n\n    - `ZOLA_VER`: Version of Zola  \n                  (e.g. `0.16.0`)\n      - Default value: `latest`\n    - `ZOLA_BASE_URL`: `base_url` for Zola to override default in comfig.toml\n\n  - For webserver image\n    \n    \u003e (Only for local `img-build.sh`, `test-img.sh` run. Currently not used on *GitLab*/*GitHub*)\n\n    - `CACHE_MAX_AGE`: Default http cache-control max-age value in seconds (for thttpd).\n                       This value can be overwritten on each container run\n                       by setting this environment variable.\n      - Default value: `600`\n\n  - For test run\n    \n    \u003e (Only for local `test-img.sh` run. Currently not used on *GitLab*/*GitHub*)\n\n    - `EXTERNAL_PORT`: external port to get http request on test run.\n      - Default value: `8000`\n\n\n\n### Environment Variables for Pages Export\n  \n  \u003e These environment variables set *path* and *authentication* information\n  \u003e of an external target repository for [Pages Export](#pages-export).\n  \u003e\n  \u003e NOTE: If Zola output site is to be served on the repository where it is pushed,\n    these environment variables should NOT be set.\n  \u003e\n  \u003e Repository address format using following variables:\n  \u003e - `REPO_PROTOCOL`://`REPO_ID`:`REPO_PW`@`REPO_HOST`/`REPO`\n  \u003e - Examples\n  \u003e   - `https://(some_GITHUB_TOKEN)@github.com/snoopy3476/Zola-Pages-Deployer`\n  \u003e   - `ssh://git@github.com/snoopy3476/Zola-Pages-Deployer`\n  \u003e     - Same with: `git@github.com:snoopy3476/Zola-Pages-Deployer`\n\n\n  - Repository path\n    \n    - `REPO_PROTOCOL`: Protocol  \n                       (e.g. `ssh`, `https`)\n      - Default value: `ssh`\n    - `REPO_HOST`: Host name of the target repository server to push pages  \n                   (e.g. `gitlab.com`, `github.com`, IP of any local hosted server)\n      - Default value: Current running server\n    - `REPO`: Repository name in the target repository server to push pages  \n              (e.g. `username/reponame`)\n      - Default value: Current repository path\n    - `REPO_BRANCH`: Branch name of the repository to push pages  \n                     (e.g. `pages`, `gh-pages`)\n      - Default value: `pages`\n\n  - Repository authentication\n  \n    \u003e If authentication error occurs after setting *repository path* variables above,\n    \u003e set appropriate authentication info to one or more of following variables\n  \n    - `REPO_ID`: ID of the target repository server to push pages  \n                 (e.g. `git`, server_token)\n      - Default value:\n        - `git` (in general cases)\n        - [**GITHUB_TOKEN**](https://docs.github.com/actions/security-guides/automatic-token-authentication) (only on *GitHub* server, and `REPO_PROTOCOL` is `https`)\n      - If you use\n        [*GitHub* personal access token (PAT)](https://docs.github.com/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)\n        to export, set a PAT value to this variable\n    - `REPO_PW`: Password of the target repository server to push pages  \n                 (WARNING: Using this variable is not recommended in general!)\n    - `REPO_KEY`: SSH private key of the target repository to push pages.\n                  Used only when `REPO_PROTOCOL` is `ssh`.\n      - Using *repository deploy key*\n        (\n         [GitLab Deploy Keys](https://docs.gitlab.com/ee/user/project/deploy_keys/)\n         /\n         [GitHub Deploy Keys](https://docs.github.com/developers/overview/managing-deploy-keys#deploy-keys)\n        )\n        is recommended, not your account SSH key directly\n        1. Create a new pair of temporary RSA key in local shell\n           (e.g. `$ ssh-keygen -m pem -t rsa -b 4096 -N '' -f ./tmpkey`)\n        2. Copy the contents of output ***private*** key,\n           and set it to this `REPO_KEY` variable\n        3. Copy the contents of output ***public*** key,\n           and add it as a new deploy key of the target repository\n           (that you want to deploy Pages).  \n           Check `Allow write access` when creating the new deploy key\n        4. Remove local temporary keys created before\n           (e.g. `$ rm ./tmpkey ./tmpkey.pub`)\n      - RSA key (starting with `-----BEGIN RSA PRIVATE KEY-----`) is recommended,\n        as SSH in *GitHub* runner does not seems to handle\n        newer, non-RSA algorithms well (e.g. ed25519)\n\n\n\n## Author\nKim Hwiwon \\\u003ckim.hwiwon@outlook.com\\\u003e\n\n\n\n## License\nThe MIT License (MIT)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkim-hwiwon%2FZola-Pages-Deployer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkim-hwiwon%2FZola-Pages-Deployer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkim-hwiwon%2FZola-Pages-Deployer/lists"}