Usage¶

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

You can disable or customize any of these steps with the Inputs. Deploying to GitHub Pages requires specific Permissions. The Outputs include the page_url and more.

Inputs¶

All Inputs are Optional.

Input	Default Value	Description of the Input
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)
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	-	Prepare script (before build)
post	-	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 reference for Workflows, Actions, and GitHub Pages.

Outputs¶

The following outputs are available.

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.

Example Outputs.

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

- name: 'Echo Output'
  run: |
    echo "GitHub page_url: ${{ steps.zensical.outputs.page_url }}"
    echo "Zensical version: ${{ steps.zensical.outputs.version }}"
    echo "Site path: ${{ steps.zensical.outputs.path }}"
    echo "Artifact name: ${{ steps.zensical.outputs.name }}"

See the Examples for more...

Question

If you need help getting started or run into any issues, support is available!