Merge branch 'dev' into main

README.md

@@ -10,7 +10,8 @@ What is it?
 Github Page Overwriter is:
 
 * the **simplest** possible Github Page publisher, because it requires no configuration
-* the **most lightweight** Github Page publisher (therefore the **fastest** possible),
+* the **most lightweight** Github Page publisher
+  (therefore the **fastest** possible - typically around 2 seconds),
   because its implementation requires no runtime dependency other than git itself.
 * the **cleanest** possible Github Page publisher,
   because it is designed to leave no extra commits in your repo history.
@@ -19,30 +20,52 @@ Github Page Overwriter is:
 How to use it?
 --------------
 
-Since Github Page Overwriter requires no configuration (more on this later),
-you simply add it as one extra step into your own github action.
+1.  Github Page Overwriter requires no mandatory configuration.
+    You simply add it as one extra step into your own github action.
 
-```yaml
-name: Your github action
+    ```yaml
+    name: Your github action
 
-on:
-  push:
-    branches:
-      - master
+    on:
+      push:
+        branches:
+          # NOTE: You may want to limit the trigger branch to be "main" or "master" etc.
+          - *
 
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out
-        uses: actions/checkout@v2
+    jobs:
+      publish:
+        runs-on: ubuntu-latest
+        steps:
+          - name: Check out
+            uses: actions/checkout@v2
 
-      - name: Generate your content
-        run: ......  # Your project's generate step here
+          - name: Generate your content
+            run: echo "Optional placeholder. Put your project's static website generator command here."
 
-      - name: Publish current workdir (which contains generated content) to GitHub Pages
-        uses: rayluo/github-pages-overwriter@v1
-```
+          - name: Publish current workdir (which contains generated content) to GitHub Pages
+            uses: rayluo/[email protected]
+
+            with:
+
+              # Optional. Default value "." means the root directory of your project will be published.
+              # You can use whatever directory your project uses, for example "wwwroot".
+              # Such a directory does *not* have to already exist in your repo,
+              # it could be an output directory created dynamically by your static website builder.
+              source-directory: .
+
+              # Optional. Default value "gh_pages".
+              # It specifies the temporary branch which hosts the static website.
+              # Each build will OVERWRITE this branch.
+              target-branch: gh_pages
+    ```
+
+
+2.  In your Github Pages setting, choose your publish source like this:
+
+    | Github Page Overwriter settings | Github Pages settings |
+    | ------------------------------- | --------------------- |
+    | `source-directory` can be any directory you choose | *Always* choose folder `/ (root)` for your publishing source, regardless of what `source-directory` is. ![Choose "/ (root)" as folder](github-pages-settings.png) |
+    | `target-branch` can be any branch that match the setting on the right | Choose any branch that matches the `target-branch` setting on the left |
 
 
 How does it work?
@@ -98,24 +121,3 @@ thus won't become part of your repo's long term history.
     D---E---F---G---H  main
    ```
 
-
-Configuration
--------------
-
-Well, you can still configure the target branch from the default `gh-pages`
-to something else you want.
-
-```yaml
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    steps:
-      - ...
-      - name: Publish generated content to GitHub Pages
-        uses: rayluo/github-pages-overwriter@v1
-        with:
-          target-branch: my_website_branch
-```
-
-But why bother? You may rather configure your Github repo to publish the conventional `gh-pages` branch instead.
-

action.yml

@@ -5,6 +5,10 @@ author: rayluo
 description: Overwrite your Github Pages branch with content of current workdir, thus deploy/publish without polluting your repo history.
 
 inputs:
+  source-directory:
+    description: The name of the source directory that you wish it to become the wwwroot of your website
+    required: false
+    default: .
   target-branch:
     description: The name of the branch that would be OVERWRITTEN by current workdir, you will then configure your Github Pages to serve this branch.
     required: false
@@ -13,24 +17,43 @@ inputs:
 runs:
   using: composite
   steps:
+
     - shell: bash
       run: |
         # The following 2 lines are not really necessary,
-        # because we do not push current branch.
-        # But we still do that here, just to be conceptually correct.
+        # because we do not intend to push current branch.
+        # But we choose to use target branch name as a temporary local work branch,
+        # thus avoid a potential error of committing to the trigger branch.
         git branch -f ${{ inputs.target-branch }} HEAD
         git checkout ${{ inputs.target-branch }}
 
+        # Generate such a new file to make sure the subsequent commit would succeed
+        # Such a file WITHOUT leading dot (.) is also visible in outcome website.
+        # FYI: filename with leading dot (.) or underscore (_) would be ignored by Jekyll,
+        # which Github Pages depends on. So we use a normal filename here.
+        date > ${{ inputs.source-directory}}/publish_date.txt
+
         # The commit and push happen to work without authentication
         # https://docs.github.com/en/actions/reference/authentication-in-a-workflow
         git config user.name "Github Pages Overwriter"
         git config user.email "[email protected]"
         git add -A
         git commit -m "Automated publish"
 
-        # Explicitly defining target,
-        # so that it would work even when target does not yet exist
-        git push -f origin HEAD:${{ inputs.target-branch }}
+    - name: Push the build output to github pages
+      shell: bash
+      ##if: ${{ inputs.source-directory == '.' }}
+      # Astonishedly, the "if" command does not work in an action shipped to marketplace,
+      # so that there is even a 3rd-party github action to do that
+      # (https://github.com/marketplace/actions/conditional-value-for-github-action)
+      # But that seems like an overkill. So, we'd use "if" in bash instead.
+      run: >  # https://yaml-multiline.info/
+        if [ "${{ inputs.source-directory }}" == "." ]; then
+          git push -f origin HEAD:${{ inputs.target-branch }}
+        else
+          # Inspired from https://gist.github.com/cobyism/4730490#gistcomment-1374989
+          git push -f origin `git subtree split -P ${{ inputs.source-directory }}`:${{ inputs.target-branch }}
+        fi
 
 branding:
   icon: copy