Zensical Action

• Features
• Inputs
  • Permissions
• Outputs
• Examples
  • Repositories
• Tags
• Support
• Contributing

Zensical GitHub Action to checkout, build, upload, and deploy Zensical Docs to GitHub Pages.

Check out the Features, Inputs and Examples for options.

name: Docs
on:
  workflow_dispatch:
  push:
    branches: [master]
jobs:
  docs:
    name: Docs
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
      url: ${{ steps.zensical.outputs.page_url }}
    steps:
      - name: Zensical Action
        id: zensical
        uses: cssnr/zensical-action@v1

All steps can be disabled or customized, see the Inputs section for options.

For more details, see the action.yml.

Features

• Build Docs
• Upload Artifact
• Deploy to Pages
• Run Pre/Post Scripts

More on the docs site: https://zensical-action.cssnr.com/

Inputs

Tip

View the Getting Started and Usage Guide online.

All Inputs are Optional.

With no inputs the workflow reference is checked out, built, uploaded, and deployed to Pages.

Input	Default Value	Description of the Input Value
version	Latest	Zensical Version
python-version	Default	Python Version (see setup-uv)
uv-version	Latest	UV Version (see setup-uv)
directory	.	Build Directory (relative to root)
path	site	Site Path (relative to root)
project	false	Set to true to install the project
checkout	true	Runs: actions/checkout
upload	github-pages	Upload: [github-pages,artifact,false]
name	artifact	Artifact Name if upload is artifact
deploy	true	Deploy to Pages (see deploy)
prepare	true	Prepare script (before build)
post	true	Post script (after build)
summary	true	Add Job Summary to Workflow

upload

Determines the type of artifact uploaded. For a normal artifact use artifact.

Default: github-pages

name

Artifact Name if upload is set to artifact.

Default: artifact

deploy

This runs actions/deploy-pages. Set to false to skip this.
Make sure you have the required permissions.

If you set upload to anything except github-pages this step will be skipped.

Default: true

prepare/post

Prepare runs after install but before build. Post runs after the build.

The paths are relative to the specified directory.

Additional Environment Variables available in these scripts.

Variable	Description
ZENSICAL_VERSION	Zensical Version Used

Permissions

If you are deploying to GitHub Pages you need these permissions.

permissions:
  pages: write
  id-token: write

Permissions documentation for Workflows, Actions, and GitHub Pages.

Outputs

Output	Description
page_url	Pages URL from actions/deploy-pages
version	Zensical Version Used for Build
path	Site Path Used for Artifact
name	Artifact name from upload step

The path will always be site or what you set for the input path.

- name: Zensical Action
  id: zensical
  uses: cssnr/zensical-action@v1

- name: Echo Output
  run: |
    echo "page_url: ${{ steps.zensical.outputs.page_url }}"
    echo "version: ${{ steps.zensical.outputs.version }}"
    echo "path: ${{ steps.zensical.outputs.path }}"
    echo "name: ${{ steps.zensical.outputs.name }}"

Examples

💡 Click on an example heading to expand or collapse the example.

Build and Deploy to GitHub Pages

name: Docs

on:
  workflow_dispatch:
  push:
    branches: [master]
    paths:
      - '.github/workflows/docs.yaml'
      - 'zensical.toml'
      - 'docs/**'

jobs:
  docs:
    name: Docs
    runs-on: ubuntu-latest
    timeout-minutes: 5

    permissions:
      pages: write
      id-token: write

    environment:
      name: github-pages
      url: ${{ steps.zensical.outputs.page_url }}

    steps:
      - name: Zensical Action
        id: zensical
        uses: cssnr/zensical-action@v1

Build and Deploy a Normal Artifact

name: Docs

on:
  workflow_dispatch:
  push:
    branches: [master]
    paths:
      - '.github/workflows/docs.yaml'
      - 'zensical.toml'
      - 'docs/**'

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Zensical Action
        uses: cssnr/zensical-action@v1
        with:
          upload: artifact

  deploy:
    name: Deploy
    uses: cssnr/workflows/.github/workflows/deploy-static.yaml@master
    needs: build
    with:
      name: github-pages
      url: https://dev-static.cssnr.com/
      robots: true
    secrets:
      host: ${{ secrets.DEV_DEPLOY_HOST }}
      port: ${{ secrets.DEV_DEPLOY_PORT }}
      user: ${{ secrets.DEV_DEPLOY_USER }}
      pass: ${{ secrets.DEV_DEPLOY_PASS }}
      webhook: ${{ secrets.DISCORD_WEBHOOK }}
    permissions:
      contents: read

Only Build the Site

name: Docs

on:
  workflow_dispatch:
  push:
    branches: [master]
    paths:
      - '.github/workflows/docs.yaml'
      - 'zensical.toml'
      - 'docs/**'

jobs:
  docs:
    name: Docs
    runs-on: ubuntu-latest
    timeout-minutes: 5

    steps:
      - name: Zensical Action
        id: zensical
        uses: cssnr/zensical-action@v1
        with:
          upload: false

      - name: Build Tree
        run: |
          tree "${{ steps.zensical.outputs.path }}"

Install Project and Run Prepare

- name: Zensical Action
  uses: cssnr/zensical-action@v1
  with:
    project: true
    prepare: 'sed -i "s/>Zensical<\/a>/>Zensical<\/a> v${ZENSICAL_VERSION}/" zensical.toml'

For more examples, you can check out other projects using this action:
https://github.com/cssnr/zensical-action/network/dependents

Repositories

Example repositories using this action to deploy to GitHub Pages.

Repository Link	Pages	Preview	Website Link
cssnr/zensical-action-docs	docs.yaml	dev.yaml	zensical-action.cssnr.com
cssnr/actions-tools	docs.yaml	dev.yaml	actions-tools.cssnr.com
cssnr/zipline-cli	docs.yaml	dev.yaml	zipline-cli.cssnr.com

Tags

The following rolling tags are maintained.

Version Tag	Rolling	Bugs	Feat.	Name	Target	Example
	✅	✅	✅	Major	vN.x.x	vN
	✅	✅	❌	Minor	vN.N.x	vN.N
	❌	❌	❌	Micro	vN.N.N	vN.N.N

You can view the release notes for each version on the releases page.

The Major tag is recommended. It is the most up-to-date and always backwards compatible. Breaking changes would result in a Major version bump. At a minimum you should use a Minor tag.

Support

For general help or to request a feature, see:

• Q&A Discussion: https://github.com/cssnr/zensical-action/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/zensical-action/discussions/categories/feature-requests

If you are experiencing an issue/bug or getting unexpected results, you can:

• Report an Issue: https://github.com/cssnr/zensical-action/issues
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY
• Provide General Feedback: https://cssnr.github.io/feedback/

For more information, see the CSSNR SUPPORT.md.

Contributing

If you would like to submit a PR, please review the CONTRIBUTING.md.

Please consider making a donation to support the development of this project and additional open source projects.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy Action
• Docker Context Action
• Actions Up Action
• Zensical Action
• VirusTotal Action
• Mirror Repository Action
• Update Version Tags Action
• Docker Tags Action
• TOML Action
• Update JSON Value Action
• JSON Key Value Check Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Package Changelog Action
• NPM Outdated Check Action
• Label Creator Action
• Algolia Crawler Action
• Upload Release Action
• Check Build Action
• Web Request Action
• Get Commit Action

❔ Unpublished Actions

These actions are not published on the Marketplace, but may be useful.

• cssnr/create-files-action - Create various files from templates.
• cssnr/draft-release-action - Keep a draft release ready to publish.
• cssnr/env-json-action - Convert env file to json or vice versa.
• cssnr/push-artifacts-action - Sync files to a remote host with rsync.
• smashedr/update-release-notes-action - Update release notes.
• smashedr/combine-release-notes-action - Combine release notes.

---

📝 Template Actions

These are basic action templates that I use for creating new actions.

• javascript-action - JavaScript
• typescript-action - TypeScript
• py-test-action - Dockerfile Python
• test-action-uv - Dockerfile Python UV
• docker-test-action - Docker Image Python

Note: The docker-test-action builds, runs and pushes images to GitHub Container Registry.

---

For a full list of current projects visit: https://cssnr.github.io/