feat: convert hugo docs workflow calls to use Taskfile task (#642)

Signed-off-by: Jeromy Cannon <[email protected]>

.github/workflows/flow-hugo-publish.yaml

@@ -18,6 +18,8 @@
 name: Deploy Hugo site to Pages
 
 on:
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
   # Runs on pushes targeting the default branch
   push:
     branches:
@@ -28,9 +30,12 @@ on:
       - '**/package*.json'
       - 'DEV.md'
       - 'README.md'
-
-  # Allows you to run this workflow manually from the Actions tab
-  workflow_dispatch:
+  # run in the pull request, but don't publish
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
@@ -81,58 +86,34 @@ jobs:
         with:
           enablement: true
 
-      - name: Install jsdoc
-        run: |
-          cd docs
-          npm i -g jsdoc
-          jsdoc --version
-          jsdoc -c jsdoc.conf.json
-          cd -
-
-      - name: Install jsdoc-to-markdown
-        run: |
-          cd docs
-          npm i -g jsdoc-to-markdown
-          jsdoc2md --version
-          ./generate_md.sh
-          cd -
-
-      - name: Copy existing documentation
-        run: |
-          mkdir -p docs/content/Developer
-          cp DEV.md docs/content/Developer/DEV.md
-          mkdir -p docs/content/User
-          cp README.md docs/content/User/README.md
+      - name: Install Task
+        uses: arduino/setup-task@b91d5d2c96a56797b48ac1e0e89220bf64044611 # v2.0.0
+        with:
+          version: 3.39.2
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Build with Hugo
-        env:
-          # For maximum backward compatibility with Hugo modules
-          HUGO_ENVIRONMENT: production
-          HUGO_ENV: production
         run: |
           cd docs
-          echo "base_url ${{ steps.pages.outputs.base_url }}"
-          echo "origin ${{ steps.pages.outputs.origin }}"
-          echo "host ${{ steps.pages.outputs.host }}"
-          echo "base_path ${{ steps.pages.outputs.base_path }}"
-          mkdir -p themes/hugo-geekdoc
-          curl -L https://github.com/thegeeklab/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1
-          ls -ltr
-          hugo version
-          hugo config
-          hugo \
-            --gc \
-            --config hugo.toml \
-            --minify \
-            --baseURL "${{ steps.pages.outputs.base_url }}/"
+          task default
 
-      - name: Upload artifact
+      # Upload the built site to GitHub Pages
+      - name: Upload Pages Artifact
         uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3.0.1
+        if: ${{ endsWith(github.ref, 'main') }}
+        with:
+          path: ./docs/public
+
+      # Upload the built site to artifacts for troubleshooting or verification
+      - name: Upload Artifact
+        uses: actions/upload-artifact@50769540e7f4bd5e21e526ee35c689e35e0d6874 # v4.4.0
+        if: ${{ !endsWith(github.ref, 'main') }}
         with:
           path: ./docs/public
 
   # Deployment job
   deploy:
+    if: ${{ endsWith(github.ref, 'main') }}
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

.gitignore

@@ -516,3 +516,10 @@ coverage/
 deleteme.yaml
 /.nyc_output/
 /.nvmrc
+/docs/public/static/Classes/
+/docs/content/Classes/
+/docs/content/Developer/DEV.md
+/docs/content/User/README.md
+/docs/themes/
+/docs/.hugo_build.lock
+/docs/public/

.remarkrc.yml

@@ -1,4 +1,5 @@
 plugins:
+  - [ 'remark-frontmatter', 'yaml', '-' ]
   # Check that markdown is consistent.
   - remark-preset-lint-consistent
   # Few recommended rules.

docs/Taskfile.yaml

@@ -0,0 +1,93 @@
+version: 3
+output: prefixed
+dotenv:
+  - .env
+silent: false
+
+env:
+  HUGO_ENVIRONMENT: production
+  HUGO_ENV: production
+  HUGO_BASE_URL: https://hashgraph.github.io/solo
+  HUGO_ORIGIN: https://hashgraph.github.io
+  HUGO_HOST: hashgraph.github.io
+  HUGO_BASEPATH: /solo
+
+tasks:
+  default:
+    cmds:
+      - task: "check-doc-dir"
+      - task: "clean"
+      - task: "install"
+      - task: "build"
+
+  start:
+    cmds:
+      - task: "default"
+      - hugo server
+
+  check-doc-dir:
+    status:
+      - |
+        if [ "$(basename "$PWD")" != "docs" ]; then
+          exit 1
+        fi
+    cmds:
+      - |
+        echo "Error: Must be in the 'docs' directory."
+        exit 1
+
+  clean:
+    cmds:
+      - rm -Rf content/Classes
+      - rm -f content/Developer/DEV.md
+      - rm -f content/User/README.md
+      - rm -Rf public
+      - rm -Rf themes
+      - rm -f .hugo_build.lock
+
+  build:
+    cmds:
+      - task: "build:jsdoc"
+      - task: "build:copy"
+      - task: "build:hugo"
+
+  build:hugo:
+    cmds:
+      - echo "base_url  $HUGO_BASE_URL"
+      - echo "origin    $HUGO_ORIGIN"
+      - echo "host      $HUGO_HOST"
+      - echo "base_path $HUGO_BASEPATH"
+      - mkdir -p themes/hugo-geekdoc
+      - curl -L https://github.com/thegeeklab/hugo-geekdoc/releases/latest/download/hugo-geekdoc.tar.gz | tar -xz -C themes/hugo-geekdoc/ --strip-components=1
+      - hugo version
+      - hugo config
+      - hugo --gc --config hugo.toml --minify --baseURL "$HUGO_BASE_URL/"
+
+  build:jsdoc:
+    cmds:
+      - jsdoc -c jsdoc.conf.json
+
+  build:copy:
+    cmds:
+      - mkdir -p content/Developer
+      - cp ../DEV.md content/Developer/DEV.md
+      - mkdir -p content/User
+      - cp ../README.md content/User/README.md
+
+  install:
+    cmds:
+      - task: "install:hugo"
+      - task: "install:jsdoc"
+
+  install:hugo:
+    status:
+      - command -v hugo
+    cmds:
+      - go install github.com/gohugoio/[email protected]
+
+  install:jsdoc:
+    status:
+      - command -v jsdoc
+    cmds:
+      - npm i -g jsdoc
+      - jsdoc --version

docs/content/_index.md

@@ -1,12 +1,10 @@
-***
-
+---
 title: Welcome to Solo Documentation
 geekdocNav: true
 geekdocAlign: center
 geekdocAnchor: false
 geekdocDescription: Home page for Solo Documentation
-
-***
+---
 
 <!-- markdownlint-capture -->
 
@@ -23,7 +21,7 @@ geekdocDescription: Home page for Solo Documentation
 
 Solo is an opinionated CLI tool to deploy and manage standalone test networks.
 
-{{< button size="large" relref="getting-started/installation.md" >}}Getting Started{{< /button >}}
+{{< button size="large" relref="User/README.md" >}}Getting Started{{< /button >}}
 
 ## Feature overview